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READ ME FIRST 

All computer software is subject to change, correction, or improvement as the manu- 
facturer receives customer comments and experiences. Radio Shack has estab- 
lished a system to keep you immediately informed of any reported problems with 
this software, and the solutions. We have a customer service network including rep- 
resentatives in many Radio Shack Computer Centers, and a large group in Fort 
Worth, Texas, to help with any specific errors you may find in your use of the pro- 
grams. We will also furnish information on any improvements or changes that are 
"cut in" on later production versions. 

To take advantage of these services, you must do three things: 

(1) Send in the postage-paid software registration card included in this manual 
immediately. (Postage must be affixed in Canada.) 

(2) If you change your address, you must send us a change of address card 
(enclosed), listing your old address exactly as it is currently on file with us. 

(3) As we furnish updates or "patches", and you update your software, you must 
keep an accurate record of the current version numbers on the logs below. 
(The version number will be furnished with each update.) 

Keep this card in your manual at all times, and refer to the current version numbers 
when requesting information or help from us. Thank you. 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK 
COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 

STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 



LIMITED WARRANTY 



CUSTOMER OBLIGATIONS 



A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the 
"Equipment"), and any copies of Radio Shack software included with the Equipment or licensed 
separately (the "Software") meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER. 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation. 

II. RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document 
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment's case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK'S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable items. 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is licensed on an "AS IS" basis, 
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

C. Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to 
give any warranties of any nature on behalf of RADIO SHACK. 

D. Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES 
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 

E. Some states do not allow limitations on how long an implied warranty lasts, so the above 
limitation(s) may not apply to CUSTOMER, 

III. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
"EQUIPMENT" OR "SOFTWARE" SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE "EQUIPMENT" OR "SOFTWARE". IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE "EQUIPMENT" 
OR "SOFTWARE". 

continued 



NOTWITHSTANDING iriE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR "EQUIPMENT" OR "SOFTWARE- 
INVOLVED. 

B. RADIO SHACK shall not be liable for anv damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

D. Some states do not allow the limitation or exclusion of incidental or consequential damages, so the 
above limitation(s) or exclusion(s) may not apply to CUSTOMER 

IV. RADIO SHACK SOFTWARE LICENSE 

RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on one computer, subject to tne following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

B. Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software. 

C. CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals if the Software permits this function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer is expressly 
prohibited from disassembling the Software 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or if additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted f o make a limited number of additional copies for 
CUSTOMER'S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third paities receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 

V. APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty >tc applicable as between RADIO SHACK and 
CUSTOMER to either a sale or the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner and/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 

VI. STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific iegal rights, and the original 
CUSTOMER may have other rights whicn vary from state to state 
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GETTING STARTED WITH OS-9 



OS-9 OPERATING SYSTEM 

For The 64K TRS-80 Color Computer 
includes an Editor and Assembler 



Radie/haek 

A DIVISION OF TANDY CORPORATION 
FORT WORTH, TEXAS 76102 



OS-9 Operating System: © 1983 Microware Systems 

Corporation and Motorola Incorporated. 
All Rights Reserved. Licensed to Tandy Corporation. 

Getting started with OS-9: 

© 1983 Tandy Corporation and Microware Systems 

Corporation. 

All Rights Reserved. 

UNIX is a trademark of Bell Laboratories. 

TRS-80 is a registered trademark of Tandy Corporation. 

Reproduction or use, without express written permission from 
Tandy Corporation or Microware Systems Corporation of any 
portion of this manual is prohibited. While reasonable efforts 
have been taken in the preparation of thrs manual to assure its 
accuracy, Tandy Corporation and Microware Systems Corpo- 
ration assumes no liability resulting from any errors or omis- 
sions in this manual, or from the use of the information 
contained herein. 

10 987654321 



To Our Customers . . . 



Congratulations on purchasing the OS -9 Disk Operating Sys- 
tem for your 64K TRS-80 Color Computer. You'll find OS-9 
powerful and simple to use. It is structured after the famous 
UNIX operating system that is used at many colleges and uni- 
versities today. 



How to Use This Manual . . . 



This manual is written for beginners although experienced pro- 
grammers will also find it useful in starting up OS-9. It explains 
the important things you need to know: 

• How to run an easy test on your disk drives. 

• How to start OS-9. 

• How to use important commands. 

• What to do in case of trouble. 

For more detailed information on OS-9, you can read these 
OS-9 manuals: 

OS-9 Commands. Explains the concepts and commands of OS-9. 

OS-9 Program Development. Explains how to use: 

• OS-9's text editor to enter programs or to prepare text 
such as letters and documents. 

• OS-9's Assembler.* 

• OS-9's Interactive Debugger to debug your assembly 
language programs.* 

OS-9 Technical Information. Provides all the information nec- 
essary to install, maintain, expand or write assembly-language 
programs for OS-9.* 

*These manuals assume that you are familiar with the 6809 
architecture, instruction set, and assembly language. 
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l/WHATISOS-9? 



What is OS-9? That's a simple question with an interesting 
answer. However, before you can understand OS-9, you need to 
understand operating systems. 



What Is an Operating System? 



An operating system acts as a manager for the computer. It 
sends information to the disk drives, printers and video. It man- 
ages the storage space on the disks and in memory. It also 
answers your commands. 

This illustration shows the relationship between the operating 
system and the hardware. (Hardware is the computer, drives 
and printer.) It also shows how application programs and lan- 
guages fit into the picture. 




Application Programs are practical uses for the computer, 
such as creating and maintaining a mailing list. 



Languages let you write your own application programs. 



Back To OS-9 



OS-9 is a versatile operating system for the 64K TRS-80 Color 
Computer It is based on the UNIX operating system developed 
by Bell Laboratories Inc. UNIX is widely used on larger com- 
puters especially in colleges and universities. 

OS-9 opens many new doors by expanding the Color Comput- 
er's capabilities. OS-9 offers sophisticated features that are nor- 
mally available only in much larger computers. Among these are: 



Multi-Level Filing System 



Like most operating systems, OS-9 lets you store information 
on disk in a "file" and index these files with a directory. OS-9, 
however, goes one step further by letting you create a hierarchy 
of directories and files. 



Multiuser/Multitasking Operation 



Multiuser means that more than one person can use the system 
at the same time. The number of users is limited by the number 
of terminals. The TRS-80 Color Computer can have one ter- 
minal; this means that two people can use OS-9 at the same 
time. One person on the Color Computer and one on the 
terminal. 

Multitasking means that two or more tasks (programs) can run 
at the same time. For example, with OS-9 you could print 
reports and enter information at the same time. 



Device-independent Input/Output System 



OS-9 uses a very efficient method for inputting and outputting 
information. It expects all input to come from the "standard 
input device" and all output go to the "standard output device." 
On the Color Computer, OS-9 expects all input to come from 
the keyboard/console and all output to go to the video display. 



You can easily "redirect" the standard I/O devices to other 
devices such as printers or disks. This means that an OS-9 pro- 
gram needs only one output routine and one input routine. 
From there you can redirect them to another device. This saves 
time for the programmer and space on the disk because pro- 
grams can be shorter. 

This manual provides step-by-step instructions for getting OS- 
9 started on your Color Computer. It includes a sample session 
to help you become familiar with some of the most common 
OS-9 commands and features. We do not cover all OS-9 fea- 
tures here, but you can find detailed information in the other 
OS-9 manuals. 

To run OS-9, you must have a 64K TRS-80 Color Computer 
that has at least one floppy disk drive. The OS-9 standard sys- 
tem disk includes modules to support the following TRS-80 
Color Computer hardware: 

• 64K RAM 

• Keyboard 

• Alphanumeric Video Display 

• Color Graphics Display 

• Disk Drives (1 or 2) 

• Joysticks ( 1 or 2) 

• Serial Printer* 

• RS-232C Communications Port 

* Optional supported hardware 

We hope you enjoy your journey with OS-9! 



2 /BEFORE YOU START OS-9 

Before you start OS-9, we suggest you run a simple test pro- 
gram to make sure your disk drives are still well "tuned." This 
test checks the speed of the drive. A disk drive speed should be 
about 300 RPM (rotations per minute). Even though we submit 
our disk drives to a rigorous quality assurance test before they 
are sent to you, the drive speed may begin to vary after use. 
This makes disks harder to read. 

You can check your drive's speed at home with the following 
procedure: 

1 . Make sure that the disk system is properly connected 
to the computer. Turn on the TV. Next, turn on the 
computer and disk drives. 

2. Insert the disk labeled OS-9 BOOT into Drive 0. 

3. At the OK prompt, type: 

RUN "*" (ENTER) 
This starts the OS-9 Utility program. 

4. The screen shows: 

b BOOT 0S9 

t TEST DISK DRIVE 

Press (T) to start the disk drive test. 

5. The test program prompts: 

***SELECT DRIVE - 3 OR "BREAK"** 
Enter a ® to test Drive 0. 



6. The screen shows the drive speed. The speed may 
change slightly during the test; this is normal. This test 
accepts speeds from 298.0 to 303.5 rpm. If the speed 
is in this range, the screen continues to display the 
speed. 

If the speed is unacceptable, the screen changes color 
and displays one of these messages: 

DISK SPEED NEEDS ADJUSTING, TOO FAST 



or 



DISK SPEED NEEDS ADJUSTING* TOO SLOW 

If one of these messages appears, take your disk drive 
to your Radio Shack Service Center for adjustment. 

To exit the test, press (BREAK] and the test prompt reappears. If 
you have only one drive, remove the OS-9 BOOT disk and 
place it in its protective sleeve. 

If you have a second drive and wish to test it, remove the OS-9 
BOOT disk from Drive and place it in Drive 1 . Press (T) at the 
test prompt, and the screen shows the drive speed. Exit the test 
by pressing (BREAK) and remove the OS-9 BOOT disk. 

Place the disk in its protective sleeve and store it in a safe place. 
You may want to run this test periodically. How often you 
decide to run it depends on how much you use your drives. 



3 /STARTING UP OS-9 



The way to start OS-9 depends on the version of your comput- 
er's disk ROM. The version number appears on the first line of 
the dialog when you start up your disk system: 

DISK EXTENDED COLOR 

BASIC 1.x <-— Version Number 

If your computer is Version 1.0, the startup procedure differs 
from that of Versions 1 . 1 and later. Versions 1.1 or later have the 
DOS command, which automatically boots OS-9. Version 1.0 
does not and must use a special command. 

Be sure your disk system is properly connected. Turn on the TV 
Then turn on the disk drives and the computer. 

Starting OS-9 With Version 1.0 

1 . Insert the disk labeled OS-9 BOOT into Drive 0. 

2. At the OK prompt, type: 



RUN "*" [ENTER] 
This starts the OS-9 Utility program. 



3. The following appears: 

b BOOT GS9 

t TEST DISK DRIUE 

Press® to boot OS-9. 

4. The boot utility prompts: 

INSERT 0S9 DISKETTE 

INTO DRIVE AND PRESS A KEY 

Remove the OS-9 BOOT disk and place the OS-9 SYSTEM 
MASTER disk in Drive 0. Press any key except break and 
OS-9 starts. 



Starting Up with Version 1.1 or Later 



1. Insert the disk labeled OS-9 SYSTEM MASTER into 
Drive 0. 

2. At the OK prompt, type: 



DOS [ESTER) 

This starts OS-9. If the DOS command returns a syntax error 
(?SN ERROR), be sure you entered the command correctly. 
If DOS still returns the error, then you probably have version 
1.0; use the previous procedure. 



Entering the Date 



After OS-9 displays its startup message, the time prompts 
displays: 

YY/MM/DD HH:MM:SS 
TIME ? 

Enter the date and time in the form shown. For example: 



BG/03/19 13:22 (INTER] 

sets the date as March 19, 1986 and the time as 1:22 pm. Enter 
the time in 24-hour notation; the seconds (:SS) are optional. 

When you enter the date, the OS-9 prompt appears: 

0S3: 

OS-9 is now in control and ready to accept a command. 

Note: You should always keep the OS-9 System Disk in 
Drive while running OS-9. 



Turning Off the System 



Before turning off your disk system, remove all disks from the 
drives. Turn off the printer (if connected), the disks, the com- 
puter and then the TV. 



4 /FORMATTING DISKS AND 
MAKING BACKUPS 



As you know from using the Color Disk BASIC, you need to 
" format' ' disks into a "file cabinet 1 ' orgainzation before using 
them. In the same manner, you must format disks before using 
them with OS-9. 

OS-9's disk format, however, is slightly different from that of 
the Color Disk BASIC. Because of this, neither can read the 
other's disk. 

This chapter shows how to format disks so that you can use 
them with OS-9. It also shows you how to make backup copies 
of them. 

The OS-9 Boot disk uses Color Disk BASIC'S format. To make 
a backup of it, use the DSK I N I command to format a blank 
disk and the BACKUP command to make a copy of the Boot 
disk. Always store your original disks in a safe place. 



Single-Drive Users 



1 . Be sure your computer and all peripherals (TV, disk drive, 
printer) are turned on. Start OS-9 as described earlier in the 
previous chapter. 

2. Get a blank disk. Be sure the write-protect notch is not 
covered by a foil tab. 

3. At the OS9: prompt, type: 

format /DO (ENTER] 
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Format displays the message: 

COLOR COMPUTER DISK FORMATTER 1*2 
FORMATTING DRIVE /DO 
Y (YES) OR N (NO) 
READY? 

Remove your OS-9 SYSTEM MASTER disk and place the 
blank disk in Drive 0. Type Y. 

4. After formatting the disk, Format prompts for a disk name. 
The name is not important at this point, so enter any letter. 
For example: 



S [ENTER) 

OS-9 begins verifying the disk. The screen shows the track 
number in hexadecimal notation as it is verified. 

5. When the formatting is complete, the OS9: prompt appears. 

Note: You cannot make a backup on a disk with errors. If 
any errors occurred during the formatting, try again. 
Remove the blank disk from Drive and replace the 
OS-9 SYSTEM MASTER disk. Repeat steps 2-5. If OS-9 
still reports errors on the disk, use another disk. 

6. Remove the formatted disk from Drive and replace the 
OS-9 SYSTEM MASTER disk. Type: 



BACKUP /DB *4BK (ENTER) 

Backup prompts: 

READY TO BACKUP FROM /DB TO /DB 
1-1 ■ 

Press (J) to begin the backup. 
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7. The following prompt appears: 

READY DESTINATION* HIT A KEY 

Remove the OS-9 SYSTEM MASTER disk and place the 
formatted disk (destination disk) in Drive 0. Press any key. 
OS-9 displays the message: 

S < — (disk name) 

IS BEING SCRATCHED 
OK ?: 

Press (¥) and the backup begins. 

8. Backup alternately prompts you to: 

READY SOURCE t HIT A KEY 

Place the OS-9 SYSTEM MASTER disk in Drive 
and press any key. 
(source - master disk) 



READY DESTINATION t HIT A KEY 

Place the formatted disk in Drive and press any key. 
(destination = formatted disk) 

9. When the backup is complete, the screen displays the num- 
ber of sectors copied and and the number of sectors verified. 
These numbers should match. 

Keep your OS-9 System backup disk in Drive 0. Store the orig- 
inal disk in a safe place. Use it only to make backups. 
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TWo-Drive Users 



1. Be sure your computer and all peripherals are turned on. 
Start OS-9 as described earlier in the previous chapter. 

2. Get a blank disk. Be sure the write-protect notch is not 
covered by a foil tab. Insert the disk into Drive 1 . 

3. At the OS9: prompt, type: 

format /Dl CENTER] 

Format displays the message: 

COLOR COMPUTER DISK FORMATTER 1,2 
FORMATTING DRIVE /Dl 
Y (YES) OR N (NO) 
READY? 

Press (Y). After formatting the disk, Format prompts you for 
a disk name. The name is not important at this point, so enter 
any letter. For example: 



S CENTER) 

OS-9 begins verifying the disk. The screen shows the track 
number in hexadecimal notation as it is verified. 

4. When the formatting is complete, the OS9: prompt appears. 

Note: You cannot make a backup on a disk with errors. If 
any errors occurred during the formatting, try again. 
Remove the blank disk from Drive and replace the 
OS-9 SYSTEM MASTER disk. Repeat steps 2-5. If OS-9 
still reports errors on the disk, use another disk. 
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5. Type: 

BACKUP CENTER) 
Backup prompts: 

READY TO BACKUP FROM /D0 TO /Dl 

Press (Y). OS-9 displays the message: 

S (disk name) 

IS BEING SCRATCHED 
OK ?: 

Press (Y) and the backup begins. 

6. When the backup is complete, the screen shows the number 
of sectors copied and the number of sectors verified. These 
numbers should match. 

Remove your OS-9 SYSTEM MASTER disk from Drive and 
move the OS-9 System backup disk from Drive 1 to Drive 0. 
Store the original disk in a safe place. Use it only to make 

backups. 

Note to Two-Drive Customers: You can format disks to 
use in your second drive (data disks) by following steps 
1-3. You can store information on the data disk instead of 
your OS-9 System Disk. 
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5 / EXPLORING THE OS-9 FILE 
SYSTEM 



OS-9 stores information in disk "files," much as you might 
store a memo or other information in a file folder. The disk files, 
however, in addition to containing ordinary information such as 
memos, lists, lines of data, and the texts of documents, can also 
contain complete programs. 

As an aid to organization, OS-9 also gives you the option of 
collecting groups of files in "directories," just as in an office 
you might organize files into categories and group them 
together in labeled file cabinet drawers. A directory might look 
like this: 



r — \ 

f directory i 



( ■" ) C 



file 2 



J C file3 J 



These directories are organized "hierarchically," similar to a 
tree or pyramid. This means that each OS-9 directory can con- 
tain another directory. 
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The OS-9 system starts at the "system device directory." This 
directory contains a directory entry for each device, such as the 
keyboard/display, disk drives, printer, and optional terminal. 
The system device directory looks like this; 



/ System \ 
( Device > 
\ Directory / 



CD GD ( 



TERM 



> GD CD 



The P is the printer, DO is the first disk drive, TERM is the 
keyboard/display, Dl is the second drive, and Tl is a terminal 
connected to the RS-232C serial port. (Even if you don't have 
the actual device, your directory still has the entry.) 
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The disk drives, (/DO and /Dl), are the only devices that can 
form their own "tree" by storing other directories and files. 
Each drive has a "root" directory which is the beginning of 
its tree. 

The following illustration shows a typical OS-9 System with a 
disk in both drives: 



/ System \ 
( Device > 
\ Directory / 



d3 GD 



TERM 



GD GD 



I DO \ 

( ROOT > 
\D I RECTORY/ 



( ROOT > 
\DI RECTORY/ 



( SYS ) ( DEFS ) ( startup ) ( CMOS ) (oS9Bool) (pAYROLl) 



(^0S9Defs) 



(memos) 



( password ) (errmssg^ ) ( motd ^ ) ( copy) ^ list ^ ( ^ dir ) ( del ) /hoURlA ^ALARIE^ / SALES ) / ACCT \ 

("a_rT?) (n _z) (a _ m) fn _ z) 



The disk in Drive is the OS-9 System disk. Its root directory 
contains two files (startup and OS-9Boot) and three sub- 
directories (SYS, DEFS and CMDS). The sub-directories con- 
tain another level of files. All of these files are necessary to 
run OS-9. 

The disk in Drive 1 is an imaginary data disk containing three 
levels of directories. OS-9 lets you organize your files with as 
many levels of directories as you need and have room for. 

Notice that all device and directory names are capitalized and 
filenames are lower-case. This is a customary practice that lets 
you easily recognize directory names; however, it is not 
mandatory. 
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Before looking at the OS-9 directory; we suggest you type the 
following command to get into the upper/lower case mode. 
(OS-9 normally displays upper-case letters only.) At the OS-9 
prompt: 

t w o d e - u p c 

OS-9 now displays lower-case characters. The Color Computer 
displays upper-case characters as dark letters on a light back- 
ground. Lower-case letters display in reverse mode, that is, 
light letters on a dark background. 

This manual shows all commands and file names in lower-case 
and directory names in upper-case. 

Note to Two-Drive Customers: The examples in this 
chapter specify Drive 0. You can use Drivel by specify- 
ing /Dl instead of/DO as shown. 

To see the contents of the OS-9 System disk's root directory, 
type the following at the OS-9 prompt: 



dip /D0 (ENTER! 

OS-9 displays: 

DIRECTORY OF . 00:27:37 
OSSBoot CMDS SYS 
DEFS startup 

This shows the first level directory on the OS-9 System disk. To 
see an example of a second level directory, look at the CMDS 
directory. Type: 



dir /D0/CMDS [ENTER] 

OS-9 lists the contents of the CMDS directory. The CMDS 
directory contains all the commands for OS-9. 

OS-9 uses "pathnames" to locate files and directories. Path- 
names describe the path to be taken. For example: 

/D0/CMDS 
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tells OS-9 that "CMDS" is located in the DO device directory. 
Look at this pathname: 

/Di/MYFILES/testpro* 

OS-9 looks for the file "testprog" in the directory MYFILES 
which is a subdirectory of device /Dl. We know that "testprog" 
is a file because it is shown in lower-case letters. 

You can position yourself in another directory by using the Chd 
command. For example, to move to the DEFS directory, type: 



chd /D0/DEFS CENTER) 
Now display the directory, using the Dir command: 



dir [ENTER] 

The Dir command always lists the contents of the current direc- 
tory if another is not specified (for example dir /DO/CMDS). 
Therefore, OS-9 displays the contents of the DEFS directory. 

If you can't remember which directory you are in, you can find 
out with the Pwd command (print working directory). Type: 



pwd (ENTER) 

OS-9 tells you that you are in the /DO/DEFS directory. Move 
back to the /DO root directory by typing: 



chd /D0 CENTER) 

Creating and Deleting Your Own Directories 

Now that you've seen some OS-9 files and directories, you 
probably want to know how to create — and delete — your own. 
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Creating Directories 



Deleting Directories 



You use the Makdir command (make directory) to create direc- 
tories. For example: 



makdir BUSINESS CENTER] 

creates a directory in the current directory (/DO) called BUSI- 
NESS. You can use the Dir command and see that BUSINESS 
has been created. (Remember, we recommend using all upper- 
case letters for directory names.) 

You can create directories to organize your files by projects, 
applications, users, and so on. Here are some sample directory 
names: 

DEE PAYROLL GROSS.SALES.TEX AS 

X10. PROJECT TESTFILES JIMS.FILES 

You can also create subdirectories (directories that reside in 
another directory). For example: 



makdir /D0/BUSINESS/PAYROLL (ENTER) 

creates a directory called PAYROLL in the BUSINESS 
directory. 



To delete a directory, use the Deldir command (delete direc- 
tory). If you want to delete the PAYROLL directory, type this 
command: 



deldir /DO/BUSINESS/PAYROLL (ENTER) 

OS-9 asks: 

LIST DIRECTORY, DELETE DIRECTORY* 

OR QUIT ? 

(L/D/0) 

Type (D) (ENTER) to delete the directory. OS-9 deletes all files in 
the PAYROLL directory and then deletes the PAYROLL 
directory. 
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Important Notes about Deleting Directories 



Keep these points in mind when deleting directories: 

• Before you delete a directory, be sure to move all impor- 
tant files to another directory or you will lose them. The 
Deldir command removes all files in the directory 
being deleted. 

• All sub-directories of the directory being deleted will be 
lost. 

• You cannot position yourself in a directory that is being 
deleted. This includes subdirectories of that directory. 
Position yourself in a directory higher in the hierarchal 
tree (use the Chd command to reposition). 
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Creating and Manipulating Files 



Although you will normally create files with application pro- 
grams, you can use the Build command to create simple files. 
To start the file, type: 

build /D0/BUSINESS/f ilel CENTER] 

This creates a file called "filer in the BUSINESS directory. 
The screen shows a question mark (?) indicating that OS-9 is 
waiting for you to insert information into the file. Type the 
following: 

? This is the first file that 
? we created* 



? CENTER] 

The CENTER] on the last line tells OS-9 to end the file and return 
the OS-9 prompt. The Dir command shows the new file: 



dir /D0/BUS1IMESS CENTER] 

Use the List command to display the contents of the file. For 
example: 



list /D0/BUSINESS/filei (ENTER] 

displays the following: 

This is the first file that 
we created i 

The Copy command lets you duplicate a file. To duplicate /DO/ 
BUSINESS/filel to the file /D0/BUSINESS/file2, type: 

copy /D0/BUSINESS/filel /D0/BUSINESS/ 



file2 CENTER] 

This tells OS-9 to create a file called "file2" and copy the con- 
tents from "filer' to "file2." The first file (filel) is left 
untouched. To see exactly what the Copy command accom- 
plished, list the contents of "file2". Type: 



list /D0/BUSINESS/f ile2 CENTER] 
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OS-9 displays: 

This is the first file that 
we created* 

Notice that "file2" is indeed a copy of "filel." You can also 
copy a file to another directory. For example: 



copy /DO/BUSINESS/f ilel /DO/filei (ENTER] 

copies the file /DO/BUSINESS/filel to file /DO/filel. Even 
though the filenames are the same, the files are unique because 
their pathnames are different. Use the Dir command to see that 
"filer' exists in both directories. 

OS-9 also lets you rename files: 



rename /D0/f i lei sawplefile (ENTER] 

This command changes the filename /DO/filel to 4 'sampler! le." 
It is important to note that this does not duplicate the file, it sim- 
ply changes the name. Therefore the file /DO/filel does not 
exist after the above command is executed. Try listing /DO/ 
filel: 

list /DB/filei (ENTER! 

OS-9 returns an Error #216, which means that OS-9 could not 
find the file. Now list /DO/samplefile: 



list /DB/samplefile CENTER] 
and OS-9 shows you its contents: 

This is the first file that 
we created* 

Remember, if you want to duplicate a file, use the Copy 
command. 

You can also delete files by using the Del command. To delete 
the file /DO/samplefile, type: 



del /DO/samplefile (ENTER] 
and OS-9 deletes "samplefile" from the /DO directory. 



25 



6 /In Case Of Trouble... 



OS-9 tells you if an error has occurred. Most errors are the 
result of making a mistake while entering the command, such 
as misspelling a command or omitting a parameter. 

When an error occurs, OS-9 displays error messages similar to 
this: 

ERROR #2 IS 

The number represents a specific type of error. This type of 
message, however, does not explain the problem. To print a 
descriptive message when an error occurs you can use the OS- 
9 Printerr command. To activate this command, type: 

printerr (ENTER] 

Now OS-9 displays errors like this: 

ERROR #2 IS 

- PATHNAME NOT FOUND 

The OS-9 error messages fall into three catagories: operator, 
hardware or software. 

An operator error tells you that you are asking the computer to 
do something it can't do. 

Perhaps the most common error is typing a command incor- 
rectly. For example, suppose you type this Dir command: 



dirr (ENTER] 

OS-9 gives you this error message: 

ERROR »21G 

- PATHNAME NOT FOUND 
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You simply need to type the command again, spelling it 
correctly: 



dir (ENTER) 

Another common operator error is trying to store too much 
information on a disk. For example, if you are in the middle of 
storing information and run out of disk space, OS-9 warns: 

ERROR #248 

- MEDIA FULL 

Either use another disk or delete some files and/or directories, 
thereby, freeing disk space. 

A hardware error warns you of a hardware problem, usually a 
flawed disk or a faulty disk drive. For example, if you tell OS-9 
to display the directory (Dir command), and the disk was for- 
matted with TRSDOS, the Color Computer Disk System's 
Operating System, OS-9 displays the message: 

ERROR #241 

- SECTOR ERROR 

Repeat the command, using an OS-9 formatted disk. Remem- 
ber, OS-9 can't read Color Computer Disk System's disks. 
OS-9 can read only those disks formatted by OS-9. 

Other hardware errors may occur such as write or read errors. 
Always try another diskette first. If the problems continue, con- 
tact your Radio Shack Service Center. 

A software error warns you of a problem in your application 
program. For example, suppose your application program tries 
to open a file in a directory where a file by that name already 
exists. OS-9 displays the message: 

ERROR #218 

- FILES ALREADY EXISTS 
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Automatic Printerr Routine 



You will probably find it more helpful to have OS-9 print a 
descriptive error message by using the Printerr command. Nor- 
mally the Printerr command is only active until you reset/reboot 
the system. 

To make it automatic on your OS-9 system, you can add the 
Printerr command to the "startup" file. Follow these steps: 

1. Display the "startup" file, by typing: 



list /DO/startup [ENTER) 

Write down the contents. If you have a printer, you can 
redirect the listing to it by typing: 

list /OB/startup >/P (ENTER) 

2. Rename "startup" to a temporary file: 

rename /D0 /start up start up*terap (ENTER) 
3. Create a new startup file: 



build startup (ENTER) 
? 

OS-9 is now ready to build a new "startup" file. First, 
enter the lines that you copied from the original file. 
Then add these lines: 



echo (ENTER) 



printerr (ENTER) 

echo Print Error Routine Now Active 

(ENTER) 

(ENTER) 

These lines activate the Printerr routine and print a 
message that the Print Error Routine is now active. 
The (ENTER) on the line by itself tells OS-9 to end the 
file. 

4. Press the reset button to load the new "startup" file. 

Now, Printerr is a permanent part of your startup file. 
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7/ AND THERE'S MORE . . . 

You've just begun to scratch the surface of OS-9. This chapter 
discusses some of the other ways you can use OS-9, through 
more commands, concepts, and programs that are becoming 
available. 

More Commands 

The following summarizes some useful OS-9 commands: 

copy — single drive (-s option) 

Copies a file from one disk to another using only one drive. For 
example: 

copy /D0/BUSINESS/f ilei /DB/newfile -s 



[ENTER) 

Copy alternately prompts you to ready the destination or source 
disk and press (0) to continue. 

date 

Displays the current system date. If you specify the t option, the 
OS-9 also displays the time. For example: 

date (ENTER) 
displays the current system date, 

date t CENTER) 
displays the current system date and time. 
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free 

Tells you the amount of free space remaining on a disk. OS-9 
displays the name of the disk and the date it was created. Next, 
it displays the total capacity of the disk (in sectors — a sector is 
equal to 256 bytes or characters), the number of unused sectors, 
and the largest block available. (A block is an area of contig- 
uous sectors.) Type: 

free CENTER) 

and OS-9 displays the amount of free space on the disk in Drive 
by default. To see how much memory is free on the disk in 
Drive 1, type: 



free /Dl [ENTER ] 

mfree 

Displays the amount of available memory in your OS-9 system. 
The screen displays the amount as "pages" of memory. A page 
is equal to 256 bytes. The address is shown for each contiguous 
set of pages as well as a total for the pages available. To see how 
much memory is available in your system, type: 



mfree [ENTER) 

setime 

Lets you set the system time and date. Type: 



setime [ENTER] 

and OS-9 prompts: 

YY/MM/DD HH:hH:SS 
TIME ? 
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To set the date as March 19, 1983, at 4: 15 PM, enter: 



83/03/19 16:15 CENTER) 

The seconds are optional. 

For more information on OS-9 commands, see OS-9 
Commands . 



Command Modifiers 



OS-9 offers a way for you to customize commands for your 
needs. You can add modifiers to almost any command line. The 
following briefly explains these modifiers. 

Alternate Memory Size. You can specify the amount of mem- 
ory to be set aside for the command by using the number sign 
symbol (#). Very often this speeds up execution of a program. 

I/O Redirection. These modifiers let you reroute a program's 
standard I/O paths to alternate files or devices. For example, a 
program that normally displays to the screen can easily output 
to the printer instead without changing the program and vice 
versa. The I/O redirection modifier symbols are <, >, and 
>>. 

Concurrent Execution. You can run two or more programs at 
the same time. The ampersand (&) tells OS-9 to start running 
that program and display another prompt. At that time you can 
start another program to run at the same time as the first. 

Pipes. Pipes transfer data between programs. The output of 
program 1 becomes the input for program2. The exclamation 
point (!) symbolizes a pipe. 

For more information on OS-9 assembly language and system 
calls see the manual, OS-9 Technical Information. For infor- 
mation on OS-9 high-level languages, check with your Radio 
Shack dealer. 
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OS-9 Languages 



OS-9 lets you use a number of different languages that were 
previously not available for the Color Computer. 

The OS-9 Assembler comes with your OS-9 system. It lets you 
write assembly language programs in 6809 code for your OS-9 

system. 

High Level Languages can also be used with OS-9. New lan- 
guages are constantly being developed, such as BASIC and 
Pascal . 

OS-9 System Calls can be used for easy communication 
between your assembly language program and OS-9. 

For more information on OS-9 assembly language and system 
calls see the manual, OS-9 Technical Information. For infor- 
mation on OS-9 high-level languages, check with your Radio 
Shack dealer. 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK 
COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 

STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 



LIMITED WARRANTY 



CUSTOMER OBLIGATIONS 



A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the 
"Equipment 1 1, and any copies of Radio Shack software included with the Equipment or licensed 
separately (the Software) meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER. 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation. 

II. RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document 
received upon purchase of the Equipment. RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects, THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADfO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment's case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK'S election and sole expense. RADFO SHACK has no obligation to replace or repair 
expendable items. 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is If censed on an "AS IS" basis, 
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radfo Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document, 

C. Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to 
give any warranties of any nature on be naif of RADFO SHACK. 

P. Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES 

OF MERCHANTABILITY OR FITHESS FOR A PARTICULAR PURPOSE. 
E. Some states do not allow limitations on how long an implied warranty lasts, so the above 

limitations) may not apply to CUSTOMER. 

IN. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
Oft DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
"EQUIPMENT" OR "SOFTWARE" SOLD- LEASED, LICENSED OR FURNISHED BY RADIO SHACK. 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE "EQUIPMENT" OR "SOFTWARE". IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT. SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE. LEASE, LICENSE, USE OR ANTICIPATED USE OF THE "EQUIPMENT" 
OR "SOFTWARE". 
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NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY 

HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 

AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR "EQUIPMENT" OR "SOFTWARE" 

INVOLVED. 

RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 

Equipment and/or Software. 

No action arising out of any cJajmed trach of this Warranty or transactions vntiBr Ms Wananty 

may be brought mora than two (2) years after the cause of action has accrued or more than Tour 

(4) years after the date of the Radio Shack sales document for the Equipment or Software, 

whichever first occurs. 

Some states do not allow the limitation or exclusion of incidental or consequential damages , so the 

above limitation^) or exclusion (s) may not apply to CUSTOMER. 



IV, RADIO SHACK SOFTWARE LICENSE 

RADID SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 

on one computer, subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 

Software. 
B Title to the medium on which thE Software is recorded {cassette and/or diskette) or stored (ROM) 

is transferred to CUSTOMER, but not title to the Software. 

C. CUSTOMER may use Software on one host computer anef access thai Software through one or 
more terminals if the Software permits this function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer Is expnssly 
prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or if additional copies are required in the operation of one computer with the Software, 
tut only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted tc make a limited number of additional copies for 
CUSTOMERS own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. Ail copyright notices staff be retained" on aff copies of the Software. 




V. APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for Lease to 
CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner find/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 

VI. STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER way foavs attar rights wftfcft wary from stele fa stats. 
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Introduction 



This Manual is designed to acquaint you, with your OS-9 
Operating System. OS-9 greatly expands the capabilities of 
your TRS-80 Color Computer, 

OS-9 is based on the UNIX operating system, often 
acclaimed as the operating system of the future because of its 
versatility, unique structure, usefulness, and user-friendli- 
ness. UNIX is widely used on large computers, and now sys- 
tems like OS-9 bring UNIX's clear advantages to owners of 
smaller computers. 

OS-9 was developed by the same people who designed the 
6809 microprocessor chip, the kk heart" 1 of the TRS-80 Color 
Computer. Unlike many other microprocessors, the 6809 is 
fully capable of running state-of-the-art software like OS-9. 
That kind of close compatibility is a real plus for the user. 

The OS-9 Operating System has many advanced features, 
which you'll learn about in this manual. By the time yoifvc 
finished reading and experimenting on your computer, you'll 
be familiar with, and ready to take advantage of OS-9 fea- 
tures like: 

• Friendly user interface and environment 

• Multi-user/multi-tasking realtime operating 
capabilities 

• Extensive support for structural, modular 
programming 

• Device-independent interrupt-driven input/output 
system 

• Multi-level, fast random-access directory and 
file system 

• Readily expandable and adaptable design 

We suggest that you read the manual chapter by chapter, ex- 
perimenting with OS~9's features and commands as you go. 
But if you're a computer veteran, and you feel you're ready 
to begin using OS-9 without any further information about it, 
you can jump ahead to Chapter 6, "OS-9 COMMANDS 1 \ 
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Whether you're a novice or a veteran you've made a wise 
choice with OS-9, and it won't be long before you discover 
for yourself its many advantages. 
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1/Introduction to the Shell 



The "shell" is the part of OS-9 that accepts commands from 
the keyboard. It's designed to provide a convenient, flexible, 
and easy-to-use interface between you and the powerful func- 
tions of the system. 

You automatically enter the shell each time you start up 
OS-9. When you see the "05-9:" prompt, that means the 
shell <s active and waiting for input — for your commands 
through the keyboard. 

Note: It doesn't matter whether you use upper-case or 
lower-case letters — or a combination of both — in 
your commands; OS-9 recognizes and handles both. 



1.1 Command Structure 



Commands — which arc really programs for the computer to 
run — can include one or more words, but they always begin 
with the name of a program. The program can be one of a 
number of things, for instance: 

• The name of a machine language program on disk. 
(Applies to experienced users, too, you'll almost al- 
ways use commands from the OS-9 disk. OS-9's 
commands are listed and explained in Chapter 6.) 

• The name of a machine language program already in 
memory. 

• The name of an executable program compiled by a 
high-level language like BASIC09, Pascal, or C (See 
Section 3.8.) 

• The name of a procedure file. (See Section 3.6.) 

When OS-9 receives a command, the shell searches for the 
appropriate program in this sequence: 

1. Memory. 

2. The "execution directory", which contains OS-9's 



command programs. (OS-9's execution directory is 
usually CMDS.) 

3. The user's tL data directory", in which the user can 
store program files as well as text files. When OS-9 
processes a file from the data directory, it runs it as 
a procedure file, assuming that the file contains 
several commands, or procedures. OS-9 will run 
them sequentially, just as if the commands had been 
manually typed in one by one. 

As soon as OS-9 locates the program, it runs it. 

Command Parameters 

The program specified in the command can be followed by 
one or more ^parameters' \ variables which give the compu- 
ter more specific instructions to follow. OS-9 automatically 
passes the parameters to the program called up by the shell 
when you enter your full command line. For example, in the 
command line: 



list f 1 lei CENTER) 

List is the name of a program that displays the contents of a 
text file, and file 1 — the specified parameter — is the name 
of the file whose contents are to be displayed. 

Note: Parameters are always separated from the com- 
mand line, and from each other, by spaces; therefore 
parameter names themselves cannot contain spaces. 
Chapter 6 discusses parameters for each of OS-9's 
commands. 

Some commands have more than one parameter. For in- 
stance, the Copy command makes an exact copy of a file. It 
requires two parameters: the name of the file to be copied, 
and the name of the file that will be the copy. So if you want 
to copy a file called startup, and call the copy newstartup, 
your command line reads: 



copy startup newstartup (ENTER] 

Other parameters let you select built-in command options. 
For instance, the Dir command by itself simply shows the 



name of all files in the user's current data directory — the 
directory in which the user is positioned when giving the 
command. 

But if you add the e (for "entire") option as a parameter, like 
this: 



dire [ENTER] 

then the output includes not only the names of the files, but 
also complete statistics about each file — the date and time 
created, size, security codes, and so forth. 

The Dir command can also accept as a parameter the name of 
a particular directory on the system. For example, the com- 
mand line: 



di r SYS (ENTER) 

produces a list of all files in the SYS directory. And the com- 
mand line: 



di r SYS e dNTlR] 
gives complete information about each file in SYS. 



di r SYS e >/P INTER) 

gives complete information about each file in SYS and re- 
directs it to the printer. 

Note: A command line can also include one or more 
"modifiers" — specifications used by the shell to alter 
the program's standard input/output files or memory 
assignments. (See Chapter 3.) 



1.2 Common Command Formats 



This section includes examples of command formats most 
commonly used with OS-9, and examples of how each com- 
mand might look as it's entered into the computer. Para- 
meters in brackets are optional; others are necessary parts of 
the command. 



FORMAT: chd DIRECTORY NAME 



EXAMPLE: chd / 00/ SYS (ENTER) 

Moves the user from the current working directory into the 
directory specified as a parameter, in this case /DO/SYS. 

FORMAT: makdir DIRECTORY NAME 



EXAMPLE: maKedir /D0/EMPLOYEES CENTER] 

Creates a new directory, in this case called /DO/EM- 
PLOYEES. You'll often want to follow this command with a 
Chd command to make the new directory your current work- 
ing directory. 



FORMAT: pwd [ENTER ] 

EXAMPLE: /D0/BU5 I NESS/ PAYROLL 

Shows the full path from the directory PAYROLL, to the 
current working directory. 

FORMAT: dir /D{)/[filauime] [c] [xj 



EXAMPLE: dir PAYROLL e CENTER) 

Lists the names of all files contained in the current working 
directory if you don't specify another. In this case, the 
PAYROLL directory is specified. The e option gives com- 
plete statistics about each file in the directory. The x option 
lists files in an execution directory rather than a data 
directory. 

Note: When you're using a command that affects direc- 
tories — and Chd. Makdir and Dir are good examples 
— make sure you specify the name of a directory and 
not a single file; otherwise, the command won't work. 
Remember: a file contains lines of text or a single pro- 
gram, and a directory is a collection of files and sub- 
ordinate directories. 

FORMAT: copy filename I filename 2 



EXAMPLE: copy m e m o s n e w m e m o s CENTER] 



Creates a new file — in this case newmemos — and then 
copies all data from memos, into it. The original file isn't 
affected. 

FORMAT: del filename 



EXAMPLE: del letters (ENTER) 

Deletes — destroys — the specified file. 

FORMAT: free DEVICENAME 

EXAMPLE: free /Dl CENTER] 

Shows how much free space remains on the specified device, 
in this case the disk on drive 1 . 

FORMAT: hst filename 



EXAMPLE: list J an K (ENTER] 

Displays on the terminal the contents — the text — of the 
specified file. 

FORMAT: rename filename 1 filename2 



EXAMPLE: rename stuff miscellany (ENTlR) 

Changes the name of a file. In this case, the file formerly 
called stuff is now named miscellany. 



1.3 Using the Video Display and Keyboard 



OS-9 has many features which expand the capability of the 
Color computer's video display and keyboard. With OS-9, 
for instance: 

• The video display has upper/lower case, screen 
pause, and graphics functions. 

• The keyboard can generate all ASCII characters. 
(Appendix C lists all characters and codes you can 
generate from the keyboard.) 



• The keyboard has a type-ahead feature that lets you 
enter data before it's requested by a program. But, 
only if the disk drives are not being accessed by a 
program. 

• The video display and keyboard together can be dealt 
with as a file. OS-9 refers to them as a file called 
/term. 



Video Display Functions 



The Color Computer normally uses only upper-ease letters. If 
you want lower-case letters (for instance, if you'd like to be 
able to send them to the printer), you can turn off the upper- 
case function with a command called tmode -upc\ You then 
see lower-case letters represented on the screen in reverse 
video (try Dir as an example) — green letters on a black 
background instead of the usual black letters on a green back- 
ground. To return to all upper-case letters, use the command 
tmode upc. 

Note: See the Keyboard Shift and Control Functions 

section for important information about shift lock 
behavior. 

The display's screen pause feature stops programs after they 
display 16 lines. Press any key to continue program output. 
You can turn screen pause off and on by using, respectively, 
the tmode -pause and tmode pause commands. 

The display system also has a complete set of commands to 
emulate commercial data terminals, plus a complete set of 
graphics commands. (They're described in detail in Appendix 
B.) 



Keyboard Shift and Control Functions 



With OS-9, several Color Computer keys have new and use- 
ful functions. 



The (SHIFT) key works something like its counterpart on a 
typewriter, letting you select upper-case or lower-case charac- 
ters. The shift lock function, which affects only letter charac- 
ters, is normally on, producing upper-case letters. To obtain a 



lower-case letter when the shift lock is on, use the (SHIFT) 
key. 

To turn off the shift lock function, press (CLEAR) and QD 
simultaneously. Then your keyboard generates lower-case 
characters, and. if you want upper-case, you use the (CLEAR) 
key. Again pressing (CLEAR) and QD simultaneously turns the 
shift lock back on. 

Note: The tmode upc function affects shift lock be- 
havior. When you're in the upc mode, upc overrides 
both the (SHIED key and the shift lock function, and 
you get only upper-case characters. In order for the 
(SHIFT] key and lock function to work, you should be 
in -upc. 

Several key combinations, when pressed simultaneously, 
generate fc 'control functions' " from the keyboard. The (CLEAR) 
QD combination, which reverses shift lock state, is a good 
example. Other control functions, and the key combinations 
that generate them, include: 

(CLEAR) CD — Repeats previous input line. Displays, 
but doesn't process, the last line entered, and posi- 
tions the cursor at the end of the line. Press (ENTER) 
to enter the line, or edit the line by backspacing. If 
you edit, you can press (CLEAR) QD again to display 
the edited line. 

(CLEAR) QD — Redisplays present input on the next 
line. 

[CLEAR] QD — Temporarily halts output to the display 
so you can read the screen be lore the data scrolls 
off. Press any single key to resume output. 

(CLEAR) CD — Stops the current running program. (The 
(BREAK) key performs the same function.) 

(SHIFT) (BREAK) — Interrupts the video display of a run- 
ning program, reactivating the shell while the pro- 
gram runs as a background task. This function is 
often referred to as CONTROL C. 



(CLEAR) (BREAK) — Sends an end-of-file message to 
programs that read input from the terminal instead of 
from a disk. Often referred to as the ESCAPE func- 
tion, this key combination must be the first character 
on a line in order to be recognized. 

(SHIFT) G*3 — Deletes the entire current line. This 
function is often referred to as CONTROL X. The 
G*3 alone, which backspaces and erases single char- 
acters, is commonly known as CONTROL H. 



NOT?:: The (CLEAR) key is used as a control key by 
OS-9. Thus, if you wanted to send a CONTROL Q 
function, you would press (CLEAR) QD simultaneously. 



1.4 Sending Output to the Printer 



Most commands and programs normally send their output to 
the Color Computer's video display. But if you want output 
to be printed, add this at the end of a command line: 

>/P 

The ">■" character tells the shell to redirect output to the 
printer through the Color Computer's RS-232 serial I/O port, 
which has the device name k 7P'\ 

If for example, you want the output from the Dir command to 
go to the printer, type: 



d i r > / P (ENTER) 



Technical Information for the RS-232 Port 



The RS-232 port can be operated at all standard baud rates, 
from 110 baud to 2400 baud. (The default speed is 600 
baud.) The character format used is 1 start bit, 8 data bits (no 
parity), 1 stop bit. 

You can use the Xmodc command to set the port's baud rate, 
end-of-line delay, auto line feed, and so forth. To examine 
the printer's current settings, type; 



xmode /P dHUH) 

Then, if you want to make changes, use the Xmodc command 
and information from this chart: 

Baud Rate Code 
110 

300 1 

600 2 

1200 3 

2400 4 

If you want, for instance, to set the port to 1200 baud, and 
the end-of-line delay (null count) to 4 character times, type: 



xmode /P baud=3 mil 1=4 (ENTER) 



2/The OS-9 File System 



This chapter gives you information about some of the most 
important elements of the OS-9 system. It acquaints you with 
the ways in which OS-9 deals with input and output, and with 
the structure and characteristics of the entire OS-9 file 
system. 



2.1 The Unified Input/Output System 



OS-9 has a unified input/output system in which data trans- 
fers to all I/O devices are performed in almost exactly the 
same way, regardless of the particular hardware devices 
involved. 

It might seem that the different operational characteristics of 
the I/O devices would make this difficult: after all line print- 
ers and disk drives behave very differently. However, OS-9 
overcomes most of these differences by defining a set of stan- 
dardized logical functions for all devices and by making the 
devices conform to these conventions, using software routines 
to eliminate hardware dependencies wherever possible. The 
result: a much simpler and more versatile input/output 
system. 

OS-9"s unified I/O system is based on logical entities called 
i/O paths' 1 . Paths are, in effect, "software channels" that 
can be routed from a program to a disk to any other I/O 
device, or even to another program. 

Data transferred through paths is processed by OS-9 to con- 
form to the hardware requirements of the specific I/O device 
involved. Data transfers can be either bidirectional (read/ 
write) or unidirectional (read only or write only), depending 
on the device and/or how you establish the path. 

Data transferred through a path is a stream of 8-bit binary 
bytes that have no specific type or value: what the data 
actually represents depends on how it's used by each pro- 
gram. This is important because it means that OS-9 doesn't 
require data to have any special format or meaning. 
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Some of the advantages of OS-9's unified I/O system arc: 

• Programs will operate correctly regardless of the par- 
ticular I/O devices selected and used when the pro- 
gram is actually executed. 

• Programs are highly portable from one computer to 
another, even when the computers have different 
kinds of I/O devices. 

• I/O can be redirected to alternate files or devices 
when the program is run, without having to alter the 
program. 

• New or special device-driver routines can easily be 
created and installed by the user. 



2.2 Organization of the File System 



Disks are multifile devices that store data — both text and 
programs — in separate logical entities called files. OS-9 
handles files in a number of ways designed to help you orga- 
nize information easily and well. 

For instance, with OS-9, groups of files can be collected into 
directories, much as in an office file folders pertaining to a 
particular subject can be gathered into a file cabinet drawer. 
Directories can in turn be collected into larger directories, just 
as several file cabinet drawers are gathered into a single file 
cabinet, and so forth. With OS-9, you can have a virtually 
limitless number of directory levels, with each directory con- 
taining other directories and/or files. 

When you're working with OS-9's files and directories — 
both the ones that come built in to the system and the ones 
you create — it's important to remember this multi-level 
''hierarchical" organization. 

In effect, it lets you build an upside-down tree, branching out 
as you go down. That way, each user on your system can 
privately organize material without affecting anyone else's 
material. You can organize your own material in particularly 
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useful ways. And both the system itself and its users ean 
easily loeate stored material. 

An OS-9 System Disk contains names of. and linkages to. all 
system I/O entities in the hierarchy. For example, a typical 
System Disk, diagrammed partially and simply, might look 
like this: 

Svstem Device I)ireclor\ 



P DO 

I 
\X) Root Directors 



■;rm 



di 



Dl Root Directory 



I 

DEFS 

I 

0S-9Dcfs 



— 1 

startup 



cop\ 



— I I — 

CMDS PAYROL 



list dir 



I 

del 



MHMOS 

, i 



SALLS ACCOUNTING 

I 

ehris 



HOURLY SALARILD 

r^i r-^-i 

a _ m n ' / a m n / 



Note: It's customary to capitalize directory names and 
to use lower-case for file names; that way. you ean tell 
at a glance what's a directory and what's a file. 

In the diagram, P is the printer; DO is the first disk drive; 
TBRM is the keyboard and video display: Dl is a second disk 
drive: and T! is the Color Computer's RS-232 serial port. 

The 'Toot directory" of DO — the "root" from which the 
rest of the disk's file system "grows" - contains a file 
called startup and two other directories, DHLS and CMDS. 

Those directories, in turn, contain files — DLFS contains a 
file called OS-9Defs and CMDS contains four files: copy, 
list, dir, and del. All these files and directories — and many 
more — come built in to the OS -9 system. 

The system diagrammed here also has a second disk, with its 
own root directory. (Root directories are automatically cre- 
ated when you initialize a disk using the format command.) 
Here the user has created directories called PAYROLL and 
MHMOS. PAYROLL, in turn, contains two other directories. 



13 



Names 



each of which contain two files. The MEMOS directory con- 
tains two directories, one of which contains a file. 



Bach file, directory, and physical I/O device on the system — 
whether it's built in or added by you — has its own name. 
When you're doing the naming, there are several things to 
keep in mind. 

Names can include from 1 to 29 characters, all of which are 
used for matching. Each name must begin with an upper- or 
lower-case letter, followed by any combination of the follow- 
ing characters: 

• Upper-case letters (A-Z) 

• Lower-case letters (a-z) 

• Decimal digits (0-9) 

• Underscoring (_) 

• Period (.) 

Some legal names, therefore, are: 

raw. data. 2 

REPORTS 

X.x 

project _ review. backup 

RJJONES 

M101968 

File and directory names like the following ones are not legal: 

190CTOBER (because it doesn't begin with a letter) 
max*min (because * isn't a legal character for 

names) 
.DATA (because it doesn't begin with a letter) 

open orders (because a name can't contain a space) 



Pathlists 
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When you want to access anything on the system — to open 
a path — you have to give OS-9 a description of the routing 
of the path. You provide the information in the form of a 
^pathlist", a list of names from the root directory down to 
the file you want to access. 



Device Names 



If, for instance — again using the diagram - — you want to 
access the chris file on the disk in Drive 1, you construct a 
pathlist by reading from the root directory to the file, listing 
the "stops along the way", and separating them with slashes, 
like this: 

/DI/MKMOS/SALKS/chris 

OS-9 uses the pathlist sequentially, from left to right, to de- 
termine that the file you want is on Device Dl, in the 
MEMOS directory, in the SALKS (sub)directory; and that its 
name is chris. 

OS-9's hierarchical organization and pathlist convention help 
you access what you need quickly and efficiently — and also 
mean that you can, if you want, have two files of the same 
name, as long as they're in separate directories; that way, of 
course, their pathlists are different. 

Note: Under some circumstances, you can take a 
"shortcut' 1 to a file, directory, or device name. See 
Working Directories in Section 2.3. 



Bach physical I/O device supported by the system has a 
unique name, defined when the system is set up and un- 
changeable while the system is running. Most of the device 
names used for the Color Computer are on the diagram. But 
in addition to P, DO, THRM, Dl, and Tl, the Color Compu- 
ter also uses PIPE. 

Device names can be used only as the first part of a pathlist, 
since they're at the root of the file system. In any pathlist, 
always precede the name of a device with a slash. 

When you're referring to a non-disk device — a terminal or 
printer, for example — use only the device name: /P, for 
instance, is the full allowable pathlist for a printer. 
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2.3 Directories 



Note: I O device names are actually the names of the 
device descriptor modules OS-s> keeps in an internal 
structure called the module directory. (See the OS-9 
Technical Information manual tor more information.) 
The module directory is automatically set up during the 
OS-9 startup sequence, and is updated as modules are 
added or deleted while the s\stem is runniim. 



On OS-9, directories, which are collections of files, are in 
reality themselves files - "superfiles , \ but still files and 
are processed by the same I/O functions used with regular 
files. 



Using Directories 



To understand how directories work, assume that the disk in 
drive one ( kk 1)1") is freshly formatted so that it has only a 
root directory. You can use the Build command to create a 
test file you call file I on /Dl. Build prints out * t '. , " , as a 
prompt to indicate that it's waiting for you to enter a text 
line. It places each line into the text file until you enter an 
empty line with only a carriage return, like this: 



build / D i / f i 1 e 1 CENTER) 

? This is the first file that CENTER 

' 7 ' we '' re creatine* CENTER) 

? (ENTER) 

If you use the l)ir command, which lists the files in a direc- 
tory, it now indicates the existence o( the new file: 



d i r / D 1 ( ENTER ) 

Directory of / D i 
file! 



15:45:29 



You can use the list command to display the text stored in the 
file: 
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1 i s t /Di/f i lei (HTER) 

This is the first file 
that we ; re creatine 

Suppose you again use the build command to create two 
more text files: 

build / D 1 / f i 1 e 2 CENTfR) 

? This is the second file [ENTER) 
? that we're creatine (ENTER) 
? (ENTER) 

build / D 1 / f l 1 e 3 (pTER) 

? This is another file* 'INTER) 

? (ENTER) 

N o w if y o ii use the D i r com n\ and* it s h o w s 
three file names: 

dir / D 1 lENJER) 

Director/ of / Dl 15 :52s 29 

f l lei f l le2 f l 1 e3 



Creating Directories 



To create a directory on the system, use the Makdir com- 
mand. With Makdir, you can create a virtually unlimited 
number o( directories on a disk. 

Suppose that for now you want to create in the /I)I root 
directory a new directory called NKWD1R. You type: 

makdir /Dl/NEWDIR CENTER) 

and the new directory is automatically part of the 1)1 root 
directory. You can check it usiniz Dir: 

d l r / D 1 (ENTER) 

Directory of / D 1 16:04:31 
f i lei f i le2 f i le3 
NEWDIR 

Now suppose you want to create a new file - a copy of 
file I. You want to call file 1. copy, for instance - in the new 
director}. Use the Copy command, like this: 
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copy /Dl/filel/DI/NEWDIR/filel» 
copy CENTEfij 

Note, thai the second paihlist now has three names: the name 
of the root directory {,D\ ), the name of the next lower direc- 
tory in the hierarchy (NhWDIR). and then the actual filename 
(filel. copy). Here's what the structure looks like now: 

D) Root Directory 

i 1 1 ~ I 

NBWDIR filel tlle2 filc3 

I 
tilel .copy 

You can use Dn command 10 see the name ol" the file in the 
new directory: 

di r /Dl/NEWDIR (ENTER ) 

Directory of /D 1 /NEWDI R 1 5 : 29 : 29 

filel. cop: 

It's possible io use Makdir to create additional new direc- 
tories in NHWDIR, and so on. Your only limit is disk space 
availability. 

Note: A file and the directory it's in must reside on the 
same device. That is, all the elements in a single path- 
list must be on the same disk. 



Deleting Directories 



To delete a directory, it's first necessary to remove all the 
files it contains. If you delete a directory while it still con- 
tains files, OS-9 has no way — no path to access those files, 
or to return their storage to the storage pool. 

Deleting a directory involves three steps: 

1. Deleting all files in the directory with the del 
command. 

2. Using the Attr command to reverse the directory 
attribute, turning the directory into a regular file. 
(See Section 2.4, The File Security System.) 
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3. Deleting the former directory — now a regular file 
— using the Del command. 

It's not a difficult process, but there's an easier way: use the 
Deldir command to perform all three steps automatically. 



Working Directories 



When you're using OS-9, you're always associated with two 
directories: a ''data directory 11 and an fc 'execution directory. 1 ' 
While you're using them, they're known as your "working 11 
or "current 11 directories. The double association allows pro- 
gram files — executable files — to be organized separately 
from data files. 

Immediately after startup, OS-9 sets the data directory to be 
the root directory of the system disk drive (usually /DO) and 
the execution directory to be the built-in CMDS directory on 
the same drive. 

Note: On timesharing systems, the Login command 
selects the user's initial data and execution directories 
according to specifications in the system password file. 

While you're on the system, OS-9 automatically selects one 
or the other of your two working directories, depending on 
the usage of the pathlist: 

• It searches the execution directory when it attempts 
to run or to load into memory files assumed to be 
executable programs. (This means that programs to 
be run as commands or loaded into memory must be 
in the execution directory.) 

• It uses the data directory for all other references, 
such as text files. 

Using Working Directories. Knowing about working direc- 
tories — current directories — can let you take "shortcuts" 
as you write out pathlists, and lets OS-9 find what you want 
more quickly: 

• If the command you're using relates to a file or a 
device not in your working directory, or in your 
working directory but above you in the hierarchy, 
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it's necessary to use a complete pathlist, starting at 
the root, for instance with /DO or /D! . 

• But if you're trying to access a file or device within 
your working directory, below you on the hierarchy, 
you can start your pathlist immediately below your 
working directory; the rest of the pathlist is implied. 

For example, if your current data directory begins with /DO, 
and you want to reach a file called baseball in the directory 
whose root is /Dl, you use its full pathlist, which might be: 

/Dl/PETE/GAMES/baseball 

in your command line. 

But if your current data directory is /D I/PETE/GAMES and 
you want to access baseball, you simply include in your com- 
mand the filename: 

baseball 

The full pathlist is implied, and processing begins with your 
current data directory. 

Puthlists using working directories can also specify additional 
lower-level directories and files. For instance, if your current 
directory is still /Dl/PETE/GAMES, you can type: 

ACTION/ racing 

in your command line, and this pathlist is implied: 

/Dl/PETE/GAMES/ACTION/racing 

If your current execution directory is /DO/CMDS, and your 
current data directory is /DO/JONES, and you type 



copy f i 1 e 1 f i 1 e 2 (ENTER] 

as your command line, in its search OS-9 expands both im- 
plied pathlists to their fullest. Written out completely, they 
look like this: 

/DO/CM DS/copy /DO/JONES/filel /D0/JONES/file2 
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Changing Working Directories. You cm make any direc- 
tory for which you have access permission your working 
directory. I he built-in shell commands Chi' aid Chx indepen- 
dently change the current data dnvctoiy and 'he current exe- 
cution directory, respectively. 

Follow the did and Chx commands wim > pathlist that de- 
scribes the new directory to which you want to go. II" your 
pathlist begins with a tie vice name. OS l J u dl begin its search 
at the device director) level up at th<* r-> *i Otherwise, its 
search will start at the current director 

For instance, suppose your current data directory is IX) 
JOHN and von want to make 1) t MY .1 ) A TAF1LKS your 
current data directory. Type: 

chd /D1/MY.DATAF1LES iENTERi 

But if you're already in 1)1 MV.DA I Al II .hS, and you want 
to move to a subdirectory called FFB.I IFFS. then you simp- 
ly type: 

chd FEB* FILES (ENTER- 

and the lull pathlist Dl MY.IM'l AFh \S FHB.FILFS - 
is implied. I'se the Chx command in exact K the same wa\ 
you use Chd. 

Anonymous Directory Names. Sometimes it's useful to be 
able to refer to your current directory, or to a higher-level 
directory, but you may not know the lull pathlist to use. Or 
you may want merely to save typing time. 

In either case. OS-9 makes special "name substitutes" 
available: 

• The name "\" refers to the current directory 

• The name "./ , refers to the "parenf of the current 
directory (the next highest-level directory in the path) 

• The name '\./' refers to the directory two levels up. 
and so on 

You can use the names in place of pathlists and or as the first 
names in pathlists. Some examples: 
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d i r ♦ INTIH) 
lists filenames in the eurrent data directory. 



d i r ♦ ♦ (ENTER] 

lists names in the current data directory's parent directory. 

del ../temp [ENTER) 

deletes the file called temp from the current data directory's 
parent directory. 

The substitute names refer to either the execution or data 
directories, depending on the context in which the names are 
used. For example, if ".." is used in a pathlist of a file 
which is executable, it represents the parent directory of the 
execution directory. Similarly, if "." is used in a pathlist 
describing a program's input file, it represents the current 
data directory. 



2.4 The File Security System 



Every file and directory has properties called "ownership" 
and "attributes", which determine who may access the file 
and how it may be used. 

OS-9 automatically stores with each file the user number 
associated with the process that created it. This user is consi- 
dered to be the owner of the file. 

Usage of security functions are based on attributes that define 
how and by whom the file can be accessed. There are a total 
of eight attributes, each of which can be turned "off or 
"on" independently. When the "d" attribute is on, it indi- 
cates that the file is a directory. The ' V attribute means that 
the file is sharable — that more than one program can read 
from the file at the same time. 

The other six attributes control whether the file can be read, 
written to, or executed, by either the owner or the "public" 
(all other users). Specifically, these six attributes are: 
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Write permission for owner: If it's on, the owner may 
write to the file or delete it. This permission can be 
used to protect important files from accidental deletion 
or modification. 

Read permission for owner: If it's on, the owner is 
allowed to read from the file. This can be used to pre- 
vent "binary" files from being used as "text" files. 

Execute permission for owner: If its on, the owner 

can load the file into memory and execute it. The file 
must contain one or more valid OS-9-format memory 
modules in order to be loadable. 

Write permission for public: If it s on. any other user 
may write to or delete the file. 

Read permission for public: If its on, an> other user 
may read (and possibly copy) the file. 

Execute permission for public: II it's on, any other 
user may execute the file. 

For example, if a particular file has all permissions on except 
"write permit to public' 1 and "read permit to public 1 ', the 
owner has unrestricted access to the file, and other users can 
execute it, but not read, copy, delete, 01 alter it. 



Examining and Changing File Attributes 



You can use the Dir command, with the e (entire) option, to 
examine the security permissions of all files in a particular 
directory. An example of output from the Dir e command 
used on the current data directory is: 
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The ''Attributes" column shows which attributes are current- 
ly on by the presence or absence of particular characters in 
this format; 
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dsewre w r 

The character positions correspond, from left to right, to; 
directory, sharable, public execute, public write, public read, 
owner execute, owner write, owner rend 

Use the Attr command to examine or change the attributes of" 
a particular file. Typing Attr followed by a filename shows 
you a file's current attributes, for example: 

attr f ile2 (INTER) 
-s-wrewr 

Reading the attributes from left to right, you can see that 
file2: is not a directory; is sharable; can't be executed by the 
public but can be written to and read by the public; and can 
be executed, written to, and read by its owner. 

If you use Attr and a filename followed by a list of one or 
more attribute abbreviations, the file's attributes will be 
changed accordingly (if, of course, it's legal for you to make 
the changes). For instance the command: 



attr f i 1 e 2 p w pt ~e - p e CENTER) 

enables public write and public read permissions and removes 
execute permission for both the owner and the public. 

Note: The d attribute behaves somewhat differently 
from the other attributes, in order to protect data stored 
in directories. You can't use Attr to turn on the d attri- 
bute — only Makdir can do that - and you can use 
Attr to turn d off only if the directory is empty. 



2.5 Reading and Writing from Files 



OS-9 uses single type and format for all files, each of which 
stores an ordered sequence of 8-bit bytes. OS-9 isn't usually 
sensitive to the contents of files for most functions. A given 
file can store a machine language program, characters of text, 
or almost anything else. Data is written to and read from files 
exactly as it's given. The file can be any size, from zero up 
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to the maximum capacity of the storage device, and can be 
expanded or shortened as desired. 

When a file is created or opened, a "file pointer 1 ' is estab- 
lished for it. Bytes within the file are addressed like memory, 
and the file pointer holds the "address" of the next byte in 
the file to be written to or read from. The OS-9 "read" and 
"write" service functions always update the pointer as data 
transfers are performed, so that successive read or write op- 
erations perform sequential data transfers. 

If you're an advanced user of the system, and particularly if 
you're using high-level languages, OS-9 is even more versa- 
tile than usual. There are certain functions that allow you to 
reposition the file pointer. 

To expand a file, you can simply write past the previous end 
of the file. Reading up to the last byte of a file causes the 
next read request to return an end-of-file status. 



File Usage in OS-9 



Even though there is physically only one type of file, the 
logical usage of files in OS-9 covers a broad spectrum. Be- 
cause all OS-9 files have the same physical type, you can use 
commands such as Copy, Del, and so forth, with any file, 
regardless of its logical usage. Similarly, a particular file can 
be treated as having different logical usages at different times 
by different programs. The main usages of files discussed 
here are: 

• Text 

• Random access data 

• Executable program modulo 

• Directories 

• Miscellaneous 

Text Files. These files contain variable-length sequences — 
lines — or ASCII characters. Each line is terminated by a 
carriage return character (ASCII code OD or decimal 13). 

Text files are used for program source code, procedure files, 
messages, documentation, and many other purposes. The 
Text Editor operates on this file format. 
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Text files are usually read sequentially, and are supported by 
almost all high-level languages (such as BASIC09 read and 
write statements). Even though it's possible to randomly ac- 
cess data at any location within a text file, it's rarely done in 
practice because lines vary in length and it's hard to locate 
the beginning of each line without actually reading the data to 
find carriage return characters. 

You can examine the content of text files by using the List 
command. 

Random-Access Data Files. Random-access data files are 
created and used primarily from within high-level languages 
like BASIC09, Pascal, C, and Cobol. In BASIC09 and Pas- 
cal, get, put, and seek functions operate on random -access 
files. 

Each file is organized as an ordered sequence of records. 
Each record is exactly the same length, so if a record's 
numerical index is given, the record's beginning address 
within the file can be computed by multiplying the record 
number by the number of bytes used for each record. Records 
can, therefore be directly accessed in any order. 

In most cases, the high-level language allows each record to 
be subdivided into fields. Each field generally has a fixed 
length and usage for all records within the file. For example, 
the first field of a record may be defined as being 25 text 
characters, the next field may be two bytes long and used to 
hold 16-bit binary numbers, and so on. 

It's important to understand that OS-9 itself doesn't directly 
process or deal with records other than by providing the basic 
file functions required by all high-level languages to create 
and use random -access files. 

Executable Program Module Files. These files are used to 
hold program modules generated by the assembler or com- 
piled by high-level languages. Each file can contain one or 
more program modules. 

OS-9 program modules resident in memory have a standard 
module format that, besides the object code, includes a 
"module header" and a CRC check value. Program modules 
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stored in files contain exact binary copies of the programs as 
they'll exist in memory, and not one byte more. Unlike many 
other operating systems, OS-9 doesn't require a "load record" 
system because OS-9 programs are position-independent and 
therefore don't have to be loaded into specific memory 
addresses. 

In order for OS-9 to load the program module(s) from a file, 
the file itself must have execute permission set, and each 
module must have a valid module header and Cylic Redun- 
dancy Checksum (CRC) value. If a program module is altered 
in any way, either as a file or in memory, its CRC check 
value is incorrect and OS-9 refuses to load the module. The 
verify command can check the correctness of the CRC 
values, and update them to corrected values if necessary. 

If a file has two or more modules, they're treated as indepen- 
dent entities after loading and they reside at different memory 
regions. 

If you attempt to use the List command on program files, or 
any other files that contain binary data, the result is a jumbled 
display or random characters and effects. Use the Dump com- 
mand to safely examine the contents of this kind of file in 
hexadecimal and controlled ASCII format. 

Directories. Directories — which are, in effect, ^superfiles" 
— play a key role in the OS-9 file system. Section 2.3 of this 
chapter describes how they're used by various OS-9 features. 
Directories can be created only by the Makdir command, and 
can be identified by the d attribute. 

Bach directory is organized into 32-byte records. Each record 
can be an entry in the directory. The first 29 bytes of the 
record is a string of characters that is the file name. The last 
character of the name has its sign bit {most significant bit) 
set. If the record isn't in use, the first character position has. 
the value zero. The last three bytes of the record is a 24-bit 
binary number that's the logical sector number where the file 
header record is located. 

The Makdir command initializes all records in a new direc- 
tory to be unused entries except for the first two entries. 
These entries have the names 'V and k \." along with the 
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logical sector numbers of the directory and its parent direc- 
tory, respectively . 

The commands Copy and List won't work with directories, 
Instead, use Dir. Directories also can't be deleted directly, 
but must first be emptied and turned into regular files. 

Miscellaneous File Usage. OS-9's basic file functions arc so 
versatile that it's possible to devise an almost unlimited num- 
ber of special-purpose file formats for particular applications, 
formats which don't fit into any of the categories discussed 
here. 

Examples of special file usage include COBOL Indexed Se- 
quential (ISAM) files and some special word processor file 
formats which allow random access of text lines, As men- 
tioned earlier most OS-9 utility commands work with any file 
format, including these special types. In general, the Dump 
command is the preferred method for examining the contents 
of unusually formatted files. 



Physical File Organization 



OS-9's file system implements universal logical organization 
for all I/O devices that effectively eliminates most hardware- 
related considerations for most applications. This section 
gives basic information about the physical file structure used 
by OS-9. (For more information, see the OS-9 Technical In- 
formation manual.) 

Each OS-9 file comprises one or more "sectors", which are 
the physical storage units of disk systems. Each sector con- 
tains 256 data bytes. Disks are numbered sequentially starting 
with sector 0, track 0. This number is called a "logical sector 
number' \ or LSN. The mapping of logical sector numbers to 
physical track/sector numbers is done by the disk driver 
module. 

A sector is the smallest allocatable physical unit on a disk 
system. However, to increase efficiency on some larger- 
capacity disk systems, OS-9 uses uniform-sized groups of 
sectors, called k 'clusters' \ as the smallest allocatable unit. 
Cluster sizes are always an integral power of two (2, 4, 8, 
and so on.) One sector of each disk is used as a bitmap 
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(usually LSN 1), in which each data bit corresponds to one 
cluster on the disk. The bits are set and cleared to indicate 
which clusters are in use, which are defective, and which are 
free for allocation to files. 

The Color Computer disk system uses this format: 

• Double-density recording on one side 

• 35 tracks per disk 

• 1 8 sectors per track 

• One sector per cluster 

On OS -9, each file has a directory entry which includes the 
filename and the logical sector number of the file's "file de- 
scriptor sector", which contains a complete description of the 
file, including: 

• attributes 

• owner 

• date and time created 

• size 

• segment list (description of data sector blocks) 

Unless the file size is zero, the file will have one or more 
sectors/clusters used to store data, The data sectors are 
grouped into one or more contiguous blocks called 
4 ' segments. 1 ' 
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3/Advanced Features Of The Shell 



Chapter 1 of this manual introduced basic shell functions and 
commands. This chapter discusses the more advanced 
capabilities of the shell. In addition to basic command line 
processing, the shell has functions that facilitate: 

• Input/Output redirection, including filters 

• Memory allocation 

• Multitasking (concurrent execution) 

• Procedure file execution 

• Built-in commands 

You can use these advanced capabilities in a virtually un- 
limited combination of ways. Of course, it's impossible to 
give more than a representative set of examples here — but 
you're encouraged to study the basic rules, use your imagina- 
tion, and explore the possibilities on your own. 

3.1 More About Command Line Processing 



The shell is a program that reads and processes command 
lines, one at a time, from its input path (usually your 
keyboard). Bach line is first scanned (or "parsed 1 ') in order 
to identify and process any of the following parts which may 
be present: 

• A program, procedure file, or built-in command 
name ("verbs") 

• Parameters to be passed to the program 

• Hxecution modifiers to be processed by the shell 

Only the verb (the program, procedure file, or command 
name) need be present; the other parts are optional. After the 
shell identifies the verb, it processes the modifiers. Any other 
text not yet processed is assumed to be parameters and is 
passed to the program being called. 

If the verb is a built-in shell command (see Section 3.5), the 
shell simply executes it. If it's not built in. the shell searches 
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for the appropriate program, and, when it finds it, runs it as a 
new process. 

Then the shell deactivates itself until the program being called 
terminates, at which time the shell takes the next input. The 
cycle continues until the shell detects an end-of-file in the 
input path. Then the shell terminates its own execution. 

Here's a sample shell command line which calls the assembler: 



asm sourcefile i - o > / P # 1 2 K (INTER) 

In this example: 

asm is the verb 

sourcefile 1 -o are parameters passed to Asm 

>/P is a modifier which redirects the 

output (the listing) to the system's 
printer 

#I2K is a modifier which requests that 

the process be assigned 12K bytes 
of memory instead o( its (smaller) 
default amount 

Note: The verb should always be the first entry in any 
line. 



3.2 Execution Modifiers 



Execution modifiers tailor (XS-9 commands to your specifica- 
tions. Type them in a command line after the verb, and cither 
before or after any parameters you Ye using. 

Execution modifiers are processed by the shell before the 
program is run. If the shell detects an error in any o\' the 
modifiers, the run is aborted and the error reported. 

Characters which compose modifiers are stripped from the 
part(s) of the command line passed to the program as para- 
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meters. Therefore, the eharaeters reserved for use as modi- 
fiers (#:!<>&) can't be used inside parameters. 



Alternate Memory Size Modifier 



When the shell involves a command program it allocates the 
program the minimum amount of working RAM memory spe- 
cified in the program's module header. (A module header is 
part of all executable programs and holds the program's 
name, size, memory requirements, and other information.) 

Sometimes it's desirable to increase this default memory size. 
You can assign memory either in 256-bytc pages by using the 
modifier #n where n is the decimal number of pages, or in 
1024- byte increments by using the modifier #nK. The two 
examples below have identical results: 



cop/ #8 f 1 lei f i le2 CENTER) 
copv »2K file! file2 



Hach command line specifies that memory size is to be 2048 
bytes. In the first command, 8*256 = 2048; in the second, 
2*1024-2048. 



I/O Redirection Modifiers 



Input/Output redirection modifiers reroute a program's stan- 
dard I/O paths to alternate files or devices. 

One of OS-^'s great advantages is that its programs use stan- 
dard I/O paths rather than individual, specific file or device 
names. It's fairly simple to redirect the I/O to any file or 
device without altering the program itself. 

Programs which normally receive input from a terminal, or 
send output to a terminal, use one or more of these three 
standard I/O paths: 

• Standard input path; Passes data from the terminal's 
keyboard to the program. 

• Standard output path: Outputs data from the program 
to the terminal's display. 
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• Standard error output path: Outputs routine status 
messages — prompts and errors, for instance — to 
the terminal's display. (The name "error output 
path" is somewhat misleading, since many kinds of 
messages besides errors travel the path.) 

Correspondingly, OS-9 offers you three redirection modifiers: 

• < redirects the standard input path 

• > redirects the standard output path 

• >> redirects the standard error output path 

When you use a redirection modifier in a command line, fol- 
low it immediately with a pathlist describing the file or device 
to or from which the I/O is to be redirected. 

For example, if you want to redirect the standard output of 
the List command to write the contents of a file called corres- 
pondence to the printer instead of to the terminal, type: 



list correspondence >/P (INTER) 

Files referenced by I/O redirection modifiers are automatical- 
ly opened, created, or closed (as appropriate) by the shell. In 
the next example, the output of the Dir command — a list of 
files in the directory MEMOS — is redirected to the file /Dl/ 
savelisting: 

DIR /DO/MEMOS >/D 1 /saue 1 i s t i r. S 



(ENTER) 

Then, if the list command is used on the file /Dl/savelisting, 
the redirected output from the Dir command is displayed like 
this: 



list /Dl/savelistin* CE NTER ] 

Directory of /D0/MEMOS 10:15::00 
Jackson fnoeller Jones 

Redirection modifiers can be used before and/or after the 
program 1 s parameters, but each modifier can be used only 
once in a command. After the program specified in the com- 
mand is run, the redirection modifier terminates with it; when 
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you run the program again, it will use its standard I/O paths 
unless you again specify otherwise. 

Note: When processes are created, they inherit their 
parent processes" standard I/O paths. Therefore, when 
the shell creates processes, they inherit its standard 
paths. 



3.3 Command Separators 



A single shell input line can request execution of more than 
one program. These programs can be executed sequentially or 
concurrently. " 'Sequential execution' ' means that one pro- 
gram must complete its function and terminate before the next 
program is allowed to begin execution. fc 'Concurrent execu- 
tion' " means that several programs are allowed to begin ex- 
ecution and run simultaneously. 



Sequential Execution 



Programs entered on separate command lines are executed se- 
quentially. But OS-9 lets you save time by specifying on a 
single command line several commands to be executed se- 
quentially. You simply separate each full command from the 
next with a semi-colon. 

For instance: 

copy nr/ f i 1 e / D I / n e w f i 1 e ? d i r > / P 



(INTER] 

According to this command, the shell first executes the Copy 
command. Then it enters the "waiting" state until Copy ter- 
minates, at which time it executes Dir. 

If an error is returned by any program, the shell doesn't ex- 
ecute subsequent commands on the same line, regardless of 
the state of the x (abort on error) option. Otherwise, ; and 
(ENTER) are identical command separators. 

Here are two more examples of commands using the semi- 
colon separator: 
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cop 1 / o 1 d f i 1 e n e w f i 1 e 5 del o 1 d f i 1 e 5 
list newfile [ENTEffi 

dir /D1/MYFILE5 list temp >/P5 
del temp dSHH) 

Note: In a command line with semi-colon separators, 
even though commands arc listed in a particular se- 
quence and executed in that sequence, they are in fact 
all separate and equal child processes of the shell. 



Concurrent Execution 



The second kind of command separator is the ampersand (&) 
which specifics concurrent execution. The first program you 
specify is run as a separate, child process of the shell. But the 
shell doesn't wait for it to finish before processing the next 
command. 

The concurrent execution separator is the way you specify 
multiprogramming (running two or more programs simul- 
taneously). With the & directing the shell to divide CPU time 
equally between the processes you name in your command 
line. 

The number of programs that can run at the same time isn't 
fixed. It depends on the amount of free memory in the system 
versus the memory requirements of the programs to be run. 

An example of a simple command line using the & separator 
is: 

di r >/P& (ENTER) 

The shell begins to run Dir sending output to the printer. It 
immediately displays both the number of the new process and 
a new prompt for you, like this: 

&007 
0S9: 

You can then enter another command, which will also be 
executed while output from your command continues to go to 
the printer. That's a real timesaver for you. You don't spend 
unproductive time waiting for OS-9 to finish a task. 
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Pipes and Filters 



Note: If you have several processes running simul- 
taneously, and want information about them, you can 
use the procs command. 

You can, if you want, use both the concurrent and sequential 
command separators in a single command line, like this: 

dir >/Pfi= list file 18: copy filel 



f i 1 e 2 ! del temp CENTER] 

Because they're joined by & modifiers, the Dir, List, and 
Copy programs run concurrently. But the Del program 
doesn't run until the others are terminated because the com- 
mand line contains a semi-colon to specify sequential execu- 
tion for Del. 



The third kind of command separator is !, which is used to 
construct "pipelines'*. Pipelines consist of two or more con- 
current programs whose standard input and/or output paths 
connect to each other using pipes" . 

Pipes are the primary means by which data is transferred from 
process to process — they're vital to interprocess com- 
munications. Pipes are first-in, first-out buffers, "holding 
areas" for data. 

I/O transfers using pipes are automatically buffered and syn- 
chronized. A single pipe can have several "readers" and 
several "writers". Multiple writers send, and multiple read- 
ers accept, data to/ from the pipe on a first-come, first-served 
basis. An end-of-file occurs if an attempt is made to read 
from a pipe when there are no writers available to send data. 
Conversely, a write error occurs if an attempt is made to 
write to a pipe with no available readers. 

Pipelines are created by the shell when it processes an input 
line with one or more ! separators. For each !, the standard 
output of the program named to the left of the ! is redirected 
through a pipe to the standard input of the program named to 
the right of the !. Individual pipes are created for each ! in the 
command line. For example: 
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update < waste r„fi le ! sort 
wnte„report > / P (ENTER) 

Here, the Update program has its input redirected (from its 
standard input, the keyboard) to become master_l'ile. The 
standard output from that first command, because of the !, 
becomes the standard input for the program sort. The output 
of sort, in turn — because o( another ! — becomes the stan- 
dard input for the program write_report, which has its stan- 
dard output redirected to the printer. 

All programs in a pipeline are executed concurrently. The 
pipes automatically synchronize the programs so the output of 
one never "gets ahead" of the input request of the next pro- 
gram in the pipeline. This means that data can't flow through 
a pipeline any faster than the slowest program can process it. 

Programs which are specifically designed to process data us- 
ing a pipeline or multiple pipelines are often called " "filters" " . 
The Tee command, which uses pipes to allow data to be 
simultaneously "broadcast" from a single input path to 
several output paths, is a useful filter. 

Some of the most useful applications of pipelines are jobs like 
character set conversion, print file formatting, data compress- 
ion/decompression . 



3.4 Command Grouping 



Sections of shell input lines can be enclosed in parentheses. 
This permits modifiers and separators to be applied to an en- 
tire set of programs. 

The shell processes the material in the parentheses by calling 
itself recursively to execute the enclosed program list. 

For example, if you want the "table of contents" of the root 
directory of drive and then the root directory of drive 1 to 
go directly to the printer, you can type either: 

dir /D0 >/P5 dir /Dl >/P (INTER) 
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(dir /D0 5 dir /Dl) >/P dHUE) 

The results are identical. The only difference is that the print- 
er is "kept"' continuously in the second example. In the first 
example, another user could ^steal 1 ' the printer in between 
the Dir commands. 

You can use command grouping to cause a group of programs 
to be executed sequentially, but also concurrently with re- 
spect to the shell that initiated them. For instance: 

(del f i 1 e i 5 del f i 1 e 2 5 del f i 1 e 3 ) & 



(ENTER) 

Here, the shell does the overall deleting process concurrently 
with whatever else you tell it to do, because you 1 re using the 
&. However, the shell deletes the three specified files 
sequentially because you're using the semicolon within the 
parentheses. 

A useful extension of this form is to construct pipelines 
consisting of both sequential and concurrent programs. For 
instance: 

(dir CMOS? dir SYS) ! friaKeuppercase 
! transmit (INTER) 

The shell first processes the output of the first Dir command 
and then the second. Then it sends all the Dir output together 
to makeuppercase; then all the output, still together, is 
transmitted. 



3.5 Built-in Shell Commands and Option: 



When processing input lines, the shell looks for several spe- 
cial names of commands or option switches that are built into 
the shell. 

These commands are executed without loading a program and 
creating a new process, and generally affect how the shell 
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operates. They can be used at the beginning of a command 
line, or following any program separator — ;, &. or !. 

Two or more adjacent built-in commands can be separated by 
spaces or commas. 

The built-in commands and their functions are: 

end path list changes the working data directory to the 

directory specified by the path list. 

chx pathlist changes the working execution directory 

to the directory specified by the pathlist. 

ex modname directly executes the module named. 

This transforms the shell process so that 
it ceases to exist, and a new module be- 
gins execution in its place. 

w waits for any process to terminate. 

* text allows you to make a ''comment". 

Whatever text you specify isn't pro- 
cessed by the shell. 

kill proc ID aborts the process specified, 

setpr procID number changes the process's priority 

number. 

x causes the shell to abort on any error. 

-x causes the shell not to abort on error. 

p turns the shell prompt and messages on 

(default). 

-p inhibits the shell prompt and messages, 

t makes the shell copy all input lines to 

output. 

~t doesn't copy input lines to output 

(default). 
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The Chd and Chx commands switch the shell's working 
directory and, by inheritance, any subsequently created child 
process. 

The Ex command is used where the shell is needed to initiate 
execution of a program without the overhead — for instance 
time spent and memory tied up — of a suspend shell process. 
The module named is processed according to standard shell 
operation, and modifiers can be used. 



3.6 Shell Procedure Files 



The shell is a reentrant program, which means that it can be 
simultaneously executed by more than one process. Like most 
other OS-9 programs, the shell uses standard I/O paths for 
routine input and output. 

OS-9's shell offers you a special feature, a time and effort 
saver called a "procedure file 1 *. A procedure file is a related 
group of commands, all of which you can execute simply by 
running the one procedure file. 

For example, the Deldir command is a procedure file that 
comes with the OS-9 system. It's actually a sequential string 
of commands (Del, Attr, and again Del), but you execute 
them all with the single command Deldir. This technique is 
sometimes called " batch' ' or 4t background' ' processing. 

Note: If you have occasion to enter the same command 
sequences repeatedly, you can build your own proce- 
dure files by using the Build command. 

A procedure file becomes, new input for the shell. By run- 
ning a procedure file, you're using the shell to create a new 
shell, a "subshell" which accepts and carries out the com- 
mands in the procedure file. 

When you enter any command line, if the shell can't find the 
specified program in memory or in the execution directory, it 
searches the data directory for a file with the specified name. 
If it finds the file, the shell automatically interprets it as a 
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procedure file, and creates the subshell, which executes the 
commands listed in the procedure file. 

Besides eliminating repetitive manual entry of commonly 
used command sequences, procedure files can allow the com- 
puter to execute a lengthy series o( programs while it's un- 
attended, or even while it's running other programs. That, of 
course, frees you to do other things. 

To run a procedure Hie — lor instance, one you've created 
and called mailsequence — type either: 

shell mailsequence (ENTER) 



mailsequence CENTER) 

Both do exactly the same thing: create a subshell which runs 
the commands you've built into your mailsequence procedure 
file. 

If you want to run a procedure file in a concurrent mode, use 
the ampersand (&) modifier. OS-9 doesn't place any con- 
straints on the number of procedure files you can run concur- 
rently, as long as there's memory available. 

You can even build procedure files so that they themselves 
cause sequential or concurrent execution of other procedure 
files. 

Note: If you're using procedure files to run programs 
you don't intend to monitor closely, it's useful to re- 
member that you can redirect standard output and stan- 
dard error output to another file. Later you can review 
the file's contents. Output redirection eliminates the 
sometimes-annoying output of shell messages on your 
terminal at random times. 



3.7 Error Reporting 



Many programs (including the shell) use OS-9's standard 
error reporting function, which displays an error number on 
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the error output path. (The standard error eodes are listed in 
Appendix A of this manual.) If, you want you can execute 
the Printer command. It replaces the smaller, built-in error 
display routine with a larger (and slower) routine that looks 
up descriptive error messages from a text file called /DO/SYS/ 
errmsq. Once you run the printer command, it can't be turned 
off. Also, its effect is system-wide. 

Programs called by the shell can return an error code in the 
tk B" register (otherwise B should be cleared) on termination. 
This type of error, as well as errors detected by the shell 
itself, causes an error message to be displayed, and proces- 
sing of the command line or procedure file to be terminated, 
unless the X (don't abort on error) built-in command has been 
executed. 



3.8 Running Compiled Intermediate Code 
Programs 



Before the shell executes a program, it checks the program 
module's language type. If it isn't 6809 machine language, 
the shell calls the appropriate run-time system tor that 
module. 

For instance, if you have BASIC09 on your OS-9 system, 
and want to run a BASIC09 I -code module called adventure, 
you can type this command: 



BASIC0S adventure (ESTER) 

or you can accomplish the same thing by typing: 

a d u e n 1 1 _i r e (TNT EF T) 

Both -command lines automatically call the BASIC09 run- 
time system. 
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3.9 Editing startup for Timesharing Systems 



Your OS-9 system has a procedure file called startup, which 
among other things, asks you for the date and time each time 
you use the system. 

If you're setting up your Color Computer as a timesharing 
system — that is, it" voir re adding a terminal to it — you 
should alter the startup file so that whoever is using the other 
terminal will have appropriate access to the system. 

Use the last command to look at the present contents of start- 
up. Remember the contents. Then use the build command to 
create a startup procedure file, exactly like the original one 
except that you add this line at the end; 

tsmon /T1& (ffiER) 

(You still have to press (ENIER) again to signal an end-of- 
file.) The tsmon command is the system's timesharing moni- 
tor, and opens standard I/O paths for the terminal, in addition 
to running the login sequence. 
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4/Multiprogramming And 
Memory Management 



One of the most valuable capabilities of OS-9 is multipro- 
gramming, which is sometimes called timesharing or multi- 
tasking. This lets your computer run more than one program 
at the same time. Multiprogramming can be a tremendous 
advantage in many situations. For example, you can be edit- 
ing one program while another is being printed. Or you can 
use your Color Computer to control household automation 
and be able to use it at the same time for routine work and 
entertainment. 

OS-9 uses this capability all the time for internal functions. 
The simple way for you to use it is by putting the & character 
at the end of a command line the & causes the shell to run 
your command as a "background", or concurrent task (see 
Chapter 3). 

In order to allow several programs to run simultaneously and 
without interference, OS-9 performs many coordination and 
resource allocation functions. The major system resources 
OS-9 manages are: 

• The input/output system 

• CPU time 

• Memory 

The input/output system is discussed in Chapter 3. This chap- 
ter is designed to give you some basic information about how 
OS-9 uses CPU time and memory to optimize system 
throughput, and to make efficient multiprogramming a 
reality. 



4.1 Processor Time Allocation and Timeslicing 



CPU time is a precious resource that must be allocated wisely 
to maximize the computer's throughput. 

Many programs by their nature spend time waiting. For ex- 
ample an interactive program, has to wait for the user to enter 
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information from the terminal. Meanwhile, the program can't 
accomplish anything. It can only wait. 

On most systems, programs tic up CPU time while they're 
waiting. But multiprogramming systems like OS-9 are far 
more efficient than that. They assign CPU time to only those 
programs that can effectively use the time. 

OS-9 uses a technique called ^timeslieing," which allows all 
active processes to share CPU time. Timeslieing uses both 
hardware and software functions, and works this way: On 
OS- 1 ), a real-time clock interrupts the Color Computer's CPU 
60 times each second. The interruption points are called 
4 'ticks' \ and the spaces between ticks are timeslices. 

Those timeslices - 60 every second — are allocated to the 
different processes on the system. At any tick, OS-9 can sus- 
pend execution of one program and begin execution of 
another. (The starting and stopping of programs doesn't affect 
their execution.) 

How frequently OS-9 gives a program timeslices depends on 
the program's assigned priority, relative to the assigned prior- 
ity of other active processes. Process priority is expressed as 
a decimal number from through 255, with representing 
the highest priority and 255 the lowest. 

OS-9 automatically gives the shell program a priority of 0. 
Since child processes inherit their parents' priorities, the 
shell's child processes all have priorities of 0. You can, if 
you want, find a process's priority number by using the Procs 
command. You can change the priority number by using the 
Setpr command. 

It's not possible to compute exactly the percentage of CPU 
time assigned to any particular process, because of dynamic 
variables such as time the process spends waiting for I/O de- 
vices. But you can roughly approximate the percentage by 
dividing the process's priority number by the sum of the 
priority numbers of all active processes: 

process's CPU share — process priority number 

sum o\' priority numbers 
of all active processes. 
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Note: Timeslicing happens so quickly that it looks to a 
human observer as if all processes are being executed 
simultaneously and continuously. If, however, the com- 
puter becomes overloaded with processing work, you 
may notice a delay in response to input from the ter- 
minal. Or you may notice that a "batch" program is 
takiniz longer than usual to run. 



4.2 Process States 



The CPU time allocation system automatically assigns pro- 
grams/processes one of three "states" that describe their cur- 
rent status. Process states are also important for coordinating 
process execution. A process can be in only one state at any 
instant, although slate changes may be frequent. The states 
are: 

• Active - Applies to processes currently able to 
work - that is, not waiting for input or for anything 
else. These are the only processes assigned CPU 
time. 

• Waiting — Applies to processes which are sus- 
pended until another process terminates. This state is 
used to coordinate execution of sequential programs. 
The shell, for example, is in the waiting state during 
the time a command program if s initiated is running. 

• Sleeping Applies to processes suspended by self- 
request for a specified time interval, or until receipt 
of a "signal". (Signals are internal messages used to 
coordinate concurrent processes.) This is the typical 
state of programs waiting for input output operations. 

Sleeping and waiting processes aren't assigned CPU time un- 
til they change to the active state. 

Note: The Procs command gives information about pro- 
cess states. 
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4.3 Creation of New Processes 



First, some terminology: when one process creates another 
process, the creator is called the "parent process", and the 
newly created process is called the "child process". The new 
child can itself become a parent by creating yet another 
process. 

It" a parent process creates more than one child process, the 
children are called "siblings" with respect to each other. II 
the parent/child relationship of all processes in the system is 
examined, a hierarchical lineage becomes evident. In fact, 
this hierarchy is a tree structure that resembles a family tree. 
(The "family" 1 concept makes it easy to describe rela- 
tionships between processes. So. it's used extensively in de- 
scriptions of (XS-9's multiprogramming functions.) 

The sequence of operations required to create a new process 
and initially allocate resources to it is automatically per- 
formed by OS-9's "fork" function. 

If for any reason any part of the sequence can't be performed, 
the fork is aborted and the prospective parent is passed an 
appropriate error code. The most frequent reason for failure is 
unavailablity oi' required resources (especially memory), or 
inability of the system to find the specified program. 

A process can create many new processes, subject only to the 
limitation of the amount of unassigned memory available. 

When the parent issues a fork request to OS-9. it must 
specify certain information: 

• A primary module, the name of the program to be 
executed by the new process. The program can 
already be present in memory, or OS-9 can load it 
from a disk file having the same name. 

• Parameters, data specified by the parent to be passed 
to and used by the new process. This data is copied 
to part of the child process's memory area. (Param- 
eters are frequently used to pass file names, in- 
itialization values, and other information.) 
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The new process also ' k inherits 4 " copies of certain of its par- 
ent's properties. These are: 

• A user number, which is used by the file security 
system and is used to identify all processes belonging 
to a specific user. (This is not the same as the ki pro- 
cess ID", which identifies a specific process.) This 
number is usually obtained from the system pass- 
word file when a user logs on. The system manager 
is always user 0. 

• Standard input and output paths, the three paths (in- 
put, output, error) used for routine input and output. 
Most paths can be shared simultaneously by two or 
more processes. 

• Current (working) directories, the data directory and 
the execution directory. 

• Process priority, which determines what proportion 
of CPU time the process receives. 

As part of the fork operation, OS-9 automatical!) assigns; 

• A process II) number, from I to 255. Hach process 
has a unique II) number, useful tor both the system 
and the user. Process ID numbers have no rela- 
tionship with the process priority numbers. Whether 
an ID number is low or high makes no difference. 

• Memory, enough for the new process to be able to 
run. In ()S- C ), all processes share a single address in 
memory. A data area, used for the program's param- 
eters, variables and stack is allocated \ov each pro- 
cess's exclusive use. A second memory area may 
also be needed to load the program if it's not resident 
in memory. 
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In Minimal'}, each new process has associated with it - from 
one source or another: 

• A primar\ module 

• Parameters 

• A user number 

• Standard I () paths 

• Current directories 

• A priority 

• An II) number 

• Ylemor\ 



4.4 Basic Memory Management Functions 



Memory management is an important OS-9 function. ()S-° 
automatical!} allocates all system memory to itself and to 
processes, and also keeps track of" the logical contents of 
memory (meaning which program modules arc resident in 
memoi} at any given time). The result is that you seldom 
ha\e to be bothered with the actual memory addresses of 
programs or data. 

Within the address space, memory is assigned from higher 
addresses downward for program modules, and from lower 
addresses upward for data area, as shown below: 



program modules 
(RAM or ROM) 



unused space 
(RAM or empty) 



data areas 
(RAM) 



highest address 



lowest address 
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Loading Program Modules into Memory 



When performing a fork operation, OS-9 first attempts to lo- 
cate the requested program module by searching the " 'module 
directory", which has the address of every module present in 
memory. The 6809 instruction set supports a type of program 
called "reentrant code", which means that the exact "copy" 
of a program can be shared by two or more different proces- 
ses simultaneously without affecting each other, provided that 
each "incarnation" of the program has an independent mem- 
ory area for its own variables. 

Almost all OS-9 family software is reentrant, and can make 
the most efficient use of memory. For instance, BASIC09 
requires 22K bytes oi memory in order to be loaded. Suppose 
that OS-9 receives a request (from a process) to run 
BASIC09. but has already caused it to be loaded into memory 
at the request of another process. OS-9 doesn't have to cause 
another copy to be loaded, using another 22K of memory. 
Instead both processes share the same copy of BAS1C09. 

OS-9 automatically keeps track o\' how many processes are 
using each program module and deletes the module when all 
processes using the module have terminated. This frees the 
modules memory for other uses. 

If the requested program module isn't already in memory, 
OS-9 uses its name as a pathlist (filename) and attempts to 
load the program from disk. 

Everv program module has a "module header" describing the 
program and its memory requirements. OS-9 uses the header 
to determine how much memory for variable storage should 
be allocated to the process. The module header also includes 
other important descriptive information about the program, 
and is an essential part of OS-9 operation at the machine lan- 
guage level. (For detailed description of memory modules 
and module headers, check the OS-9 Technical Information 
manual.) 

Programs can also be explicitly loaded into memory using the 
Load command. As with "fork", the program is actually 
loaded only if it isn't already in memory. 
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If the module isn't in memory, OS -9 copies the requested 
module from the file into memory and verifies the CRC. If the 
module isn't already in the module directory, OS-9 adds it to the 
directory. This process is repeated until all the modules in the 
file are loaded, the 64 K memory limit is exceeded, or until a 
module with an invalid format is encountered. OS-9 always 
links to the first module read from the file. 

If the program module is already in memory, the load process 
still begins in the same way: OS-9 loads the module from the 
file and verifies the CRC. Hut then when it attempts to add 
the module to the module directory, and notices that the mod- 
ule is already known there, it merely increments the known 
module's link count — the number of processes using the 
module. 

You can use Load to "lock" a program into memory. That's 
a timesaver if you need to use the same program repeatedly. 
With Load the program is kept continuously in memory . OS- 
9 doesn't have to take the time to load it each time you use it. 

The opposite of Load is the Unlink command, which de- 
creases a program module's link count by one. When this 
count becomes zero, indicating that the module is no longer 
used by any process, the module is deleted. Its memory is 
deallocated and its name is removed from the module direc- 
tory. The Unlink command is generally used in conjunction 
with the Load command. (Programs loaded by "fork" are 
automatically unlinked when the program terminates). 

Suppose, for instance, you're planning to use the Copy com- 
mand 10 times in a row. Normally the Copy program is 
loaded each time you enter the Copy command. But if you 
lock the Copy module into memory, and then enter your 
string of commands, you won't have to wait while Copy is 
loaded and unloaded repeatedly. You'll finish your work 
more quickly. When you're done, use Unlink to unlock the 
module from memory. The sequence looks like this: 
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load copy (ENTER) 

copv f i lei f i 1 e 1 a i ENTER' 

copy file2 fileZa (ENTER) 

copy f l le3 f i le3a ENTERi 

copy f i le4 fi le4a 'ENTER' 

copy fileS file5a 'ENTER) 

copy f l leG f i leGa 'ENTER!' 

copy file? f i le"7a ENTER) 

copy files f i leSa ENTER 1 

copy fileS fileS a 'ENTER) 

copy file 10 filel I? a ENTERj 
unl ink copy f ENTER) 

It's important to use Unlink after the program is no Ionizer 
needed; otherwise the program eontinues to occupy memory 
which could be used tor other purposes. 

Note: He verv careful not to unlink modules in use bv 
any process, or you'll cause the memory used b\ the 
module to be deallocated, ami its contents destroyed. 
The result is a user's nightmare: ali programs using the 
unlinked module crash. 



Loading Multiple Programs: 



Another important aspect o( program loading is the ability to 
have two or more programs resident in memory at the same 
time. This is possible because all OS- 1 ) program modules are 
written as "position-independent code", or "IMC"' PIC 
programs don't have to be loaded into specific, predetermined 
memorv addresses to work correctly. The\ can, therefore be 
loaded at different memorv addresses at different times. 

PIC programs require special types of machine language in- 
structions which few computers have. The abilitv of the 680°- 
microprocessor to use this type of program is one o\ its most 
powerful features, and one o\ the greatest aids toward multi- 
programming. 

Since more than one program can reside in memory, you can 
therefore use the Load command two or more times (or have 
a single file contain several memory modules), and each 
program module is automatical!) loaded at different, non- 
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overlapping addresses. (Most other operating systems write 
over the previous program's memory whenever a new pro- 
gram is loaded). 

This technique also means that you don't have to he directly 
concerned with absolute memory addresses. 

Note: Any number of program modules can be loaded 
until available system memorv is full. 



Memory Fragmentation 



Kven though PIC programs can be loaded initially at any 
address where Tree memorv is available, program modules 
can't be relocated dynamically afterwards. That means that 
once a program is loaded, it must remain at the address at 
which it was originally loaded. 

This characteristic can lead to a sometimes troublesome phe- 
nomenon called "memory fragmentation". When a program 
is loaded, it's assigned the first sufficiently large block of 
memory at the highest address possible in the address space. 
If several program modules are loaded, and subsequently one 
or more modules located iti between other modules is un- 
linked there'll be several fragments of free memory space. 
The sum of the sizes of the \ivo memory spaces may be quite 
large. Hut because they're scattered, there won't be enough 
free space in a single block to load a program module larger 
than the largest free space. 

The Mfree command shows the location and si/e of each un- 
used memorv area, and the Mdir e command shows the 
address, si/e, and link (use) count of each module in the 
address space. You can use both commands to detect frag- 
mentation. And you can usually ^defragment" memory by 
unlinking scattered modules and reloading them. (Make cer- 
tain none of the modules is in use before doing so.) 
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5/Use Of The System Disk 



OS- 1 ) s\ steins use a svstcm disk to load manv parts o| the 
opciatmg system during svstem startup, and to pimide files 
frequentlv used cturi 1111 normal svstem operations. Therclore. 
the system disk is generallv kept in disk drive zero ( DO) 
when the sWciu is tunning. 

Two Tiles used during the system sKntup operation. OS^Hoot 
and startup are provided and must temain in the system disk\ 
root directors. Other tiles on the sWem disk are organized 
into three direetones; CMDS ( commands), DKPS (system- 
wide definitions), and SYS (othci svstem tiles). Still other 
files and directories created by the svstem manager and or 
users ean also reside on the s\stem disk. (These Irequentlv 
include each user's initial data directors . ) 



5.1 The OS9BOOT File 



The file called OSWoot is loaded into RAM mentors b\ the 
"bootstrap" routine located in the OS- 1 ) lirmware. It includes 
file managers, device drivers and desenptors. and anv other 
modules which are permancntk resident in mentor). The OS- 
L ) Svstcm Master Disks OS\>Boot tile contains these modules; 

lOMan OS- ( ) input output manager 

RBI Random Mock (disk) file manager 

SCI' Sequential character (terminal) 

file manager 

PipcMan Pipeline file manager 

Riper Pipeline driver 

Pipe Pipeline device descriptor 

IT IO Kc\ board video graphics device driver 

PRINTPR Printer device driver 

RS2M RS-2M serial port device driver 

CVDisk Disk driver 
DO. 1)1. 1)2. 1)3 Disk device descriptor 

TPRM Terminal device descriptor 

P Printer device descriptor 

Tl RS-232 serial port device descriptor 

Shell Input Output commands interlace module 
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PI Printer (serial) device descriptor 

Clock Real-time clock module 

SYSGO System startup process 

You can create new bootstrap files, which can include addi- 
tional modules, by using the ()S9Gen command. Any module 
loaded as part of the bootstrap can't be unlinked, and is 
stored in memory with a minimum o\~ fragmentation. You 
may find it advantageous to include in the OS^Boot file any 
module you use constantly during normal system operation. 



5.2 The SYS Directory 



The directory 'DO/SYS contains two important files: 

• password (the system password file see the Login 
command) 

• errmsq (the error message file see 3.7) 

These files, and the SYS directory itself, aren't absolutely 
required to boot OS-9. but they're needed if you plan to use 
Login, Tsmon. or Printerr. You can add other system-wide 
files o( a similar nature, if you want to. 



5.3 The startup File 



The title <I)()/startup is a shell procedure file which is auto- 
matically processed immediately after system startup. You 
can include in startup any legal shell command line. Many 
people choose to include Set i me to start the system clock. If 
this file isn't present, the system will still start correctly but 
you have to run Set i me manually. 
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5.4 The CMDS Directory 



The directory /DO/CM DS is the system-wide command object 
code directory, normally shared by all users as their working 
execution directory. The vital shell program is part of CMDS. 
The system startup process "sysgo" makes CMDS the initial 
execution directory. 



5.5 The DEFS Directory 



The directory /DO/DFFS contains assembly language source 
code Tiles. They in turn contain common system- wide sym- 
bolic definitions normally included in assembly language pro- 
grams by means of the OS -9 assembler ' 'use" ' directive. The 
presence and use of this directory is optional, but highly rec- 
ommended for any system used for assembly language pro- 
grams. The files commonly contained in this directory are: 

• OS9I)efs Main system-wide definition file 

• RBFDefs — RBF file manager definition file 

• SCFDefs SCF file manager definition file 

• SysType — System types definition file 



5.6 Changing System Disks 



Most OS- 1 ) users prefer to leave the system disk in place 
while the system is running, particularly with multiuser sys- 
tems. Leaving it in place guarantees that it won't be taken 
away just when someone is using it. 

If you do remove the disk and begin to use another one. let 
OS-9 know where you want to be on the new disk by using 
the Chd and Chx commands. (For directions, see Chapters 2 
and 6.) Those commands set both working directory pointers 
— data and execution — for the new disk. 
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In general, it's unwise to remove a disk and insert another 
while any files are open. And it's just plain dangerous to your 
data to make a disk exchange if" any files on the first disk are 
open in the * 'write" or " update" modes. 



5.7 Making New System Disks 



To make a system disk, it's necessary to ilo these four things: 

1 . Format the new disk 

2. Create and link the ()S9Boot file by using the 
()S9(ien or Cobbler command 

3. Create or copy the startup file 

4. Copy the CMOS and SYS directories, and the files 
they contain 

You can perform steps 2 through 4 manually, or do them 
automatically by using any one of these methods: 

• Create and use a shell procedure file 

• Use a shell procedure file generated by the Dsave 
command 

• Use the Backup command 



58 



6/System Command Descriptions 



This chapter contains alphabetical descriptions of each of the 
command programs supplied with OS-9. The commands are 
ordinarily called using the shell, but can also be called from 
most other programs in the OS-9 family, including BASIC09. 
Interactive Debugger, Macro Text Editor, and others. Unless 
otherwise noted, the programs described in this section are 
designed to run as individual processes. 



6.1 Organization of Entries 

Kaeh command entry is organized to include: 

• The name of the command 

• A "syntax" line, which shows you what format, or 
"syntax" to use when you type the command 

• A brief definition of what the command does 

• Further details about the command and how to use it 

• Information about any options available with the 
command 

• One or more examples of command usage 

6.2 Command Syntax Notations 



It's important to enter the various parts of a command in the 
correct order, and in the correct format. The syntax line in 
each command description helps you do that by showing you 
exactly what each command requires. 

The syntax line always begins with the name of the com- 
mand. Occasionally, that's all you'll need (except, of course, 
for pressing (ENTER)). Hut other commands either require, or 
will accept, parameters - variables which give instructions 
to OS-9. And man} commands offer you built-in options. 
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The syntax line gives you that information by using these 
notations: 

Italics — Italics indicates a variable for you to supply, for 
instance the name of a file {filename), a directory {direc- 
tory name), or a complete path to a file or directory {path- 
name). Some other variables are: devices [devname), 
memory modules {modname), process ID numbers (pro- 
cID), options {options), a list of parameters {paramlist), 
and text {text). (In a command situation, text means a 
character string terminated by an cnd-of-line.) Another 
variable you will encounter is arglist* or argument list. 
Similar to paramlist. but is generally broader in scope, 
including modifiers, program specifications and so forth. 

[ ] — Brackets indicate that the material within them is 

optional to the command. 

... — An ellipsis indicates that the material immediately pre- 
ceding can be repeated within the command. For instance, 
\fi/ename]\... ) means that you can, specify more than one 
filename to the command. 

The command syntax doesnT include the shell's built-in op- 
tions (for instance I/O redirection), because the shell filters 
out its options before the command line is passed to the pro- 
gram being called. 



6.3 System Commands 



This section describes the format and use of OS- - commands. 

The following list is a summary of these commands: 

Attr Change file attributes 

Backup Make disk backup 

Bincx Convert binary to s-record 

Build Build text file 

Chd Change working data directory 

Chx Change working execution directory 

Cmp File comparison utility 

Cobbler Make bootstrap file 
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Copy Copy data 

Date Display system date and time 

Dcheck Cheek disk file structure 

Del Delete a file 

Deldir Delete all files in a directory system 

Dir Display file names in a directory 

Display Display converted characters 

Dsave Generate procedure file to copy files 

Dump Formatted file dump 

Echo Hcho text to output path 

Exbin Convert s-record to binary 

Format Initialize disk media 

Free Display free space on device 

Ident Print OS-9 module identification 

Kill Abort a process 

Link Link module into memory 

List List contents of disk file 

Load Load module(s) into memory 

Login Timesharing system log-in 

Makdir Create directory file 

Mdir Display module directory 

Merge Copy and combine files 

Mfree Display free system RAM memory 

OS9Gcn Build and link a bootstrap file 

Printerr Print full-text error messages 

Procs Display processes 

Pwd Print working directory 

Pxd Print execution directory 

Rename Change file name 

Save Save memory module(s) on a file 

Setimc Activate and set system clock 

Setpr Set process priority 

Sleep Suspend process for period of time 

Shell OS-9 command interpreter 

Tee Copy standard input to multiple output paths 

Tmode Change terminal operating mode 

Tsmon Timesharing monitor 

Unlink Unlink memory module 

Verify Verify or update module header and CRC 

Xmode Examine or change device initialization mode 
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ATTR 

ATTR filename [ permission abbreviations ] 

Examines or changes the security permissions of a file. 

To enter the command, type Attr followed by the name of the 
file whose security permissions are to be changed. Then type 
a list of permissions which are to be turned on or off. A 
permission is turned on by giving its abbreviation, or turned 
off by preceding its abbreviation with a minus sign. Permis- 
sions not explicitly named arc not affected. If no permissions 
are given, the current file attributes will be printed. 

You can't change the attributes of a file you don't own. User 
zero, can change the attributes of any file in the system. 

File permission abbreviations are: 

d Directory 

s Shareable file 

r Read permit to owner 

w Write permit to owner 

e Execute permit to owner 

pr Read permit to public 

pw Write permit to public 

pe Execute permit to public 

You can use the Attr command to change a directory to a file 
if all entries have been deleted from it. You can't change a 
file to a directory with this command (see Makdir). 



Examples: 



attr mv file -pr -pw (ENTlE) 

removes read and write permissions from the public. 

attr m v f i 1 e r w e pr pw p e dNTER) 

gives the file's owner, and the public, read, write and execute 
permissions. 
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attr d a t a 1 o a (ENTER) 

- s - w r - w r 

Since the command doesn't specify permissions, Attr displays 
the current permissions of the Catalog file. 



BACKUP 

BACKUP [e] [s] [-v] [devnarne] [devname] 

Physically copies all data from one device to another. 

A physical copy is performed, sector by sector, without re- 
gard to file structures. In almost all cases, the devices speci- 
fied must have exactly, the same format (size, density, and so 
forth) and must not have defective sectors. 

If you omit both device names, the names /DO and ID\ are 
assumed. If you omit only the second device name, a single- 
unit backup will be performed on the drive specified. 

Options are: 

e Exits if any read error occurs 

s Prints single-drive prompt message 

-v Does not verify 

#nK Allow more memory (n = amount of memory), 
and therefore speed up the backup procedure 

Examples: 

backup /D2 /D3 (ENTER) 

makes a backup of the diskette in Drive 2 on to the diskette in 
Drive 3. 

backup -u CENTER) 

assumes the names 130 and Dl, and makes the appropriate 
backup without verification. 
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backup (ENTER) 

Ready to BACKUP from /D0 to 



/Dl ?: Y (ENTER) 
MYDISK 

is b e i n a scratched 
OK ?: Y 

Number of sectors copied: $0276 

Verify pass 

Number of sectors verified: $027G 

This example shows a complete interchange between the 
Backup command and the user who entered it. In the example 
/Dl, the destination disk, is named MYDISK. "Scratched" 
means "erased". 

The following is an example of a single-drive backup. Back- 
up reads a portion of the source disk into memory and then 
prompts you to remove the source disk and put the destination 
disk into the drive. Then Backup writes on the destination 
disk. Then you remove the destination disk and put the source 
disk back into the drive. This continues until Backup copies 
the entire disk. Giving Backup as much memory as possible 
will necessitate fewer disk exchanges. 



backup /D0 #32K (ENTER) 

Ready to BACKUP from /D0 to 

D0 ?: Y 

Ready DESTINATION, hit a key: 

MYDISK 

is b e i n £ scratched 
OK ?: Y 

Ready SOURCE, hit a key: 
Ready DESTINATION, hit a key: 
Ready SOURCE, hit a key: 
Ready DESTINATION, hit a key: 

(several repetitions) 

Ready DESTINATION, hit a Key: 
Number of sectors copied: $0276 
Verify pass 
Number of sectors verified: $ 2 7 S 
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BINEX 
EXBIN 



BINEX filename I filename! 
EXBIN filename I filename! 



Binex converts a binary file into an S-Record file, and Kxbin 
converts an S-Reeord file into a binary file. 

An S-Record file is a type of text file that contains records 
representing binary data in hexadecimal character form. This 
Motorola-standard format is often directly accepted by com- 
mercial PROM programmers, emulators, logic analyzers and 
similar devices that are RS-232- interfaced. It can also be use- 
ful for transmitting files over data links that can handle only 
character-type data; or to convert OS-9 assembler- or com- 
piler-generated programs to load on non-OS-9 systems. 

Binex converts filename h an OS-9 binary format file, to a 
new file named file nam e2 in S-Record format. If you invoke 
Binex on a non-binary load module file, OS-9 prints a warn- 
ing message and asks you if Binex should proceed anyway. A 
•'Y" response means yes; any other answer will terminate the 
program. S- Records have a header record to store the pro- 
gram name for informational purposes, and each data record 
has an absolute memory address which is not meaningful to 
OS-9 since it uses position-independent code. However, the 
S-Reeord format requires them, so Binex will prompt the user 
for a program name and starting load address. For example: 

binex / D / C M D S / s c a n n e r s c a n n e r ♦ S 1 

(TnTFRD 

Enter starting address for files 

$100 

Enter name for header records 
scan n e r 

To download the program to a device such as a PROM pro- 
grammer (for example, using serial port /Tl), type: 

list scanner, SI >/Tl (ENTER) 
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Exbin is the inverse operation; filename/ is assumed to be an 
S- Record format text file which Exbin converts to pure binary 
form on a new file called filename!. The load addresses of 
each data record must describe continguous data in ascending 
order. 

Exbin doesn't generate or check for the proper OS-9 module 
headers or CRC check value required to actually load the 
binary headers or CRC check value required to actually load 
the binary file. You can use the Ident or Verify commands to 
check the validity of the modules if they're to be loaded or 
run. 



Example: 



exbin p r o 3 r a m * S 1 
(ENTER) 



CMDS/p rotf ram 



BUILD 

BUILD filename 



Builds short text files by copying the standard input path into 
the file specified by filename. Build creates a file according 
to the filename parameter, then displays a k '? ,, prompt to 
request an input line. Each line entered is written to the out- 
put path (the file). Entering a line consisting of only a car- 
riage return terminates Build. 

Examples: 



build s m a 1 1 _ f i 1 e dBUB) 

creates a new file called small _ file and puts into it whatever 
you type at the keyboard. 



b u i 1 d / P dNTH) 
directs whatever you type to the printer. 



b u i 1 d < wytext / T 1 (ENTER) 
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Using Build, you can also transfer, or redirect, material from 
one file to another. Instead of the keyboard, the standard in- 
put path is the first file you name in the command. The out- 
put path is the second. In this example, the mytext file 
becomes the input path, and is copied to Terminal 1 , the out- 
put path. 



b u i 1 d newfile 



THE POWERS OF THE OS-S CENTER) 
OPERATING SYSTEM ARE TRULY dHUB 
FANTASTIC* (MIE) 

CEHUB 



list newfile (ENHH) 

THE POWERS OF THE OS-9 
OPERATING SYSTEM ARE TRULY 
FANTASTIC* 

This example shows an interchange between Build and the 
user. After building newfile, the user employs the List com- 
mand to check the contents of the newly built file. 



CHD 
CHX 

CHD pathname or directory name 
CHX pathname or directory name 



Chd changes the current data directory, and Chx changes the 
current execution directory. 

Many commands in OS -9 work with user data such as text 
files, programs and so forth. These commands assume that 
a file is located in the working data directory. Other OS -9 
commands assume that a file is in the working execution 
directory. 
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The Chd and Chx commands don't appear in the CMDS 
directory, because they're built in to the shell. 

Examples: 



chd /DI/PROGRAMS ( ENTER) 

change the current data directory the PROGRAMS data direc- 
tory located on the diskette in drive 1 . This example shows 
the use of a pathname. 

chx . ♦ (INTER) 

moves the user to the directory immediately above the current 
execution directory. 

chx binarv^files/text-prosframs 



(INTER) 

is another example of the use of a pathname to change 
another execution directory. 



chx /D0/CMDS? chd /Dl INTlR) 
chanties both the execution and data directories. 



CMP 



CMP filename 1 : filename! 



Opens two files and performs a comparison of the binary 
values of the corresponding data bytes of the files. 

If any differences are encountered, the file offset (address) 
and the values of the bytes from each file are displayed in 
hexadecimal. 

The comparison ends when an end-of-file marker is encoun- 
tered on cither file. Cmp then displays a summary of the 
number of bytes compared and the number of differences 
found. 
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Examples: 



cfrip re 


d blue 


(ENTER) 


Dif f e 


rences 




b y t e 


#1 


#2 


00000013 


00 


01 


00000022 


B0 


Bl 


0000002A 


9B 


AB 


0000002B 


3B 


3G 


0000002C 


GD 


G5 


Bytes compared: 


0000002D 


Bytes d 1 f f 


■ e r e n t ; 
d red 


: 00000005 


c fii p re 


[ENTER] 



Diffe rences 

N o n e ♦ ♦ ♦ 

Bytes compared: 0000002D 
Bytes different: 00000000 



COBBLER 



COBBLER devname 



Creates the OS-9BOOT file required on any disk from which 
OS-9 is to be bootstrapped. 

The boot file consists of the same modules which were loaded 
into memory during the most recent bootstrap. (To add mod- 
ules to the bootstrap file use the OS9Gen command.) Cobbler 
also writes the OS-9 kernel on the first fifteen sectors of track 
34, and excludes these sectors from the diskette allocation 
map. If any files are present on these sectors, Cobbler will 
display an error message. 

The boot file must fit into one contiguous block on the disk- 
ette. For this reason, Cobbler is normally used on a freshly 
formatted diskette. If Cobbler is used on a diskette without a 
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contiguous block of storage large enough to hold the boot 
file, the old boot file may be destroyed, and OS-9 won't be 
able to boot from that diskette until it's reformatted. 

Example: 

cobbler /D0 CENTER) 

WARNING - FILE(S) OR KERNEL 
PRESENT ON TRACK 34 - THIS 
TRACK NOT REWRITTEN 

Saves current device attributes on the current system disk. 

Note: This command is often used after Xmode to per- 
manently change device attributes. 



COPY 



COPY pathname pathname [-s] 



Copies data from the first file or device specified to the 
second. 

'The first file or device must already exist. The second file is 
automatically created if the second pathname is a file on a 
diskette. Data can be of any type and is not modified in any 
way as it's copied. 

Copy transfers data using large block reads and writes until it 
reaches an end-of-file marker on the input path. Because 
block transfers arc used, normal output processing of data 
doesn't occur on character-oriented devices such as terminals 
and printers. Therefore it's better to use List Copy when a 
file consisting of text is to be sent to a terminal or printer. 
With Copy, important codes (e.g. line feed) won't be added. 

The -s option causes Copy to perform a single-drive copy 
operation. The second pathname must be a full one if you use 
-s. In a single-drive procedure. Copy reads a portion of the 
source disk into memory. Then you remove the source disk 
and put the destination disk into the drive, and enter a "C M 
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then Copy writes on the destination disk, with the process 
continuing until the entire file is copied. 

Using the shells alternate memory size modifier to give a 
large memory space increases speed and reduces the number 
of media exchanges required for single-drive copies. 

Examples: 

copy filel fileZ «15K ( ENTER ) 

copies filel to file2 giving \5K of memory. 

copy /Dl/JOE/news /D0/PETER 
messages C ENTER] 

copies the news file on the diskette in Drive 1 to the mes- 
sages file on the diskette in Drive 0. 



copy /TERM /P (ENTER) 

sends — copies to the printer of anything you type into the 
console. 

copy /D0/cat / D / a n i m a 1 s / c a t 



-s *32K ( ENTER ) 

Ready DESTINATION* hit C to 

conti ri Lie: c 
Ready SOURCE* hit C to continues c 
Ready DESTINATION* hit C to 

c o n t i n u e s c 

This is an example of the alternating method used in a single- 
drive copy operation. 



DATE 

DATE [t] 



Displays the current date, and. if you use the t option, the 
current system time. 
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Examples: 

date t (ENTER) 
displays the system date and time 

date t >/P QENTER) 
direets the command's output to the printer. 

setime INUR) 

YY/MM/DD HH t hM.8S 
TIME? 81/04/15 14.19*00 

date CENTER) 

April 15. 1981 

date t (INTER) 

April 15 f 1981 14.20*20 

This sequence illustrates setting a new date and time for the 
system by using the Setime command, and then using Date 
and it's t option to check system date and time. 



DCHECK 

DCHECK [-opts] devname 

Checks disk file structure. 



It's possible lor sectors on a diskette to be marked as being 
allocated, but in fact not to be actually associated with a file 
or the diskette's free space. This can happen if a diskette is 
removed from a drive while files are still open, or if a direc- 
tory which still contains files is deleted. Deheck is a diagnos- 
tic you can use to detect this condition, as well as to check 
the general integrity of the directory/file linkages. 

Deheck is given the drive number of the diskette to be 
checked as a parameter. After verifying and printing some 
vital file structure parameters, Deheck follows pointers down 
the diskette's file system tree to all directories and files on the 
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diskette. As it docs so, it verifies the integrity of the file 
descriptor sectors, reports any discrepancies in the directory/ 
file linkages, and builds a sector allocation map from the seg- 
ment list associated with each file. If any file descriptor sec- 
tors (FDS) describes a segment with a cluster not within the 
file structure of the diskette, Dchcck reports a message like 
this: 

*** Bad FD segment ($x\xyxy-$vvvvvv) for file: 
(pathname) 

This indicates that a segment starting at sector xvxvxv and 
ending at sector vvvvvv can't really be on this diskette. 
There's a good chance the entire FD is bad if any of its seg- 
ment descriptors is bad. The allocation map is not updated for 
corrupt FDs. 

While building the allocation map, Dchcck also makes sure 
that each diskette cluster appears once and only once in the 
file structure. If it discovers duplication, Dcheck displays a 
message like: 

Cluster Sxvxvxv was previously allocated 

This message indicates that Dcheck has found cluster xyxvxy 
at least once before in the file structure. The message may be 
printed more than once if a cluster appears in a segment in 
more than one file. 

Then Dcheck compares the newly created allocation map with 
the allocation map stored on the diskette, and reports any 
differences in messages like: 

Cluster Sxvxvxv in allocation map but not in file 

structure 

Cluster Sxvxvxv in file structure but not in allocation 

map 

The first message indicates that sector number xva.vxy (hexa- 
decimal) was found not to be part of the file system, but was 
marked as allocated in the diskette's allocation map. In addi- 
tion to the causes mentioned in the first paragraph, some sec- 
tors may have been excluded from the allocation map by the 
Format program because they were defective. Or they may be 
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the last few sectors of the diskette, the sum of which was too 
small to compose a cluster. 

The second message indicates that the cluster starting at sec- 
tor xv.v.vxv is part of the file structure but is not marked as 
allocated in the diskette's allocation map. It's possible that 
this cluster may be allocated to another file later, overwriting 
the contents of the cluster with data from the newly allocated 
file. (Any clusters that have been reported as "previously 
allocated" by Dcheck, as described above, surely have this 
problem.) 

Dcheck options include: 

-s Displays count of files and directories 

only 
-b Suppresses listing of unused clusters 

-p Prints pathnames for questionable 

clusters 
-w = pathname Specifies path to directory for work 

files 
-m Saves allocation map work files 

-o Prints Dcheck's valid options 

The -s option causes Dcheck to display a count of files and 
directories only. Only FDs are cheeked for validity. The -b 
option suppresses listing of clusters allocated but not in file 
structure. The -p option causes Dcheck to make a second pass 
through the file structure, printing the pathlists for any clus- 
ters that Dcheck finds as "already allocated" or "in file 
structure but not in allocation map". The -w option tells 
Dcheck where to locate its allocation map work file(s). The 
pathname specified must be a full pathname for a directory. 
(The directory /DO is used if -w is not specified.) It is recom- 
mended that this path list not be located on the diskette being 
Dchecked if the diskette's file structure integrity is in doubt. 

Dcheck builds its diskette allocation map in a file called path- 
/k//w/Dcheckpp(), where pathname is as specified by the -w 
option, and pp is the process number in hexadecimal. Each 
bit in this bitmap file corresponds to a cluster of sectors on 
the diskette. If the -p option appears on the command line, 
Dcheck creates a second bitmap file {<pathname2>! 
Dcheckppl) that has a bit set for each cluster Dcheck finds as 
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^previously allocated" or kt in file structure but not in alloca- 
tion map". Dchcck then makes another pass through the 
directory structure to determine the pathnames for these ques- 
tionable clusters. You can save the bitmap work files by 
specifying the -m option on the command line. 

For best results, Dcheck should have exclusive access to the 
diskette being checked. Otherwise Dcheck may be fooled if 
the diskette allocation map changes while it's building its bit- 
map file from the changing file structure. Dcheck can't pro- 
cess diskettes with a directory depth greater than 39 levels. 

Examples: 



dchecK /D2 (ENTER) 

V oluiiie - ' M y s y s t e m disk' o n 

deuice /D2 
$ 9 A bytes in al location map 
1 sector per cluster 
$000276 total sectors on media 
Sector $000002 is start of root 

directory F D 
$0010 sectors used for i d * 

allocation map and root 

d i rectory 
Building allocation map work 

filE.i. 
Checking allocation m a p file* ♦ ♦ 

'My system disk 7 file structure is 
intact 

1 directory 

2 files 

dcheck -mpw = /D2 /D0 (ENJIR) 

M olume - ' S y s t e m d i s K '' o n device 

/D0 
$ # S b y t e s in allocation map 
1 sector per cluster 
$00022A total sectors on media 
Sector $000002 is start of root 

directory F D 
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$0010 secto 


alloc at io 


d i rectory 


Building a 1 


f i le ♦ ♦ ♦ 


Cluster 800 


allocated 


*** Bad FD 


$23ABF0) 


JunKv • f i 1 


Checking a 1 


Cluster $00 


hi u t not i 


Cluster $00 


b u t not i 


Cluster $00 


b u t not i 


Cluster $00 


b u t n o t i 



r s used for id* 
n map and root 

location map work 

4 was previously 

segment ($111111- 
for file: /D0/TEXT/ 



location map 
0038 in file 
i"! allocation 
003B in file 
n allocation 
1 B 3 in allocation 
n file structure 
01BB in allocation 
n file structure 



f i le . ♦ ♦ 

st ructare 

map 

st ructure 

map 

map 

map 



Pathlists for questionable 

clusterss 
Cluster $000038 in path: 

/d0/OS9boot 
Cluster $00003B in path: 

/d0/OS9boot 
Cluster $000040 in path: 

/d0/OS3boot 
Cluster $000040 in path: 

/ d / t e s t / d o u b 1 e ♦ f i 1 e 

1 previously a 1 1 o c a t e ■ i cluster 
f o u n d 

2 clusters in file structure but 
not in allocation map 

2 clusters in allocation map but 

not in file structure 
1 bad file descriptor sector 

'System disk' file structure is 

not intact 
5 directories 
25 f l les 
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DEL 

DEL [-x] filename [...] 

Deletes the file(s) specified. 



You must have write permission for the file(s). Directories 
cannot be deleted unless they're changed to files or you use 
the Deldir command. (See the Attr command description.) 

If you use the -x option, Del assumes the current execution 
directory. 

Examples: 

del text_pro#ram ald-test_protfram 



(ENTER! 

deletes the two files specified. 

del /Dl/riLimbe r„f i Me (ENTER) 

uses a complete pathname to specify the file named number _ 
five on the diskette in Drive I . 

del - x c m d s ♦ s u b d i r / f i 1 e ( ENTER) 

specifies a file called cmds.subdir/file in the current execution 
directory. 

dir / D 1 [ENTER] 

director/ of /Dl 14 ♦29*46 
m /file newf ile 



del newfile (ENTER) 



d i r / D 1 INTER) 

directory of /Dl 14*30*37 
m /file 

In this interchange, the user first employs the Dir command 
to see what files are in the /Dl directory. Command output 
indicates that /Dl has two files: my file and newfile. The user 
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employs the Del command to delete newfile. and then uses 
Dir again to make certain that newfile has been deleted. 



DELDIR 

DELDIR directory name 

Deletes all files in a directory and the directory itself. 

This command is a convenient alternative to manually delet- 
ing directories and the files they contain. Use it only when 
you want to delete everything in a directory, including the 
directory itself, other directories and all the subdirectories and 
files in them. 

When Deldir runs, it prints a prompt message after the com- 
mand line: 

deldi r OLDFILES dNTEl) 
Deleting directory file* 
List directory t "delete 'directory* 
or quit ? ( 1 / d / q ) 

An 1 response causes a Dir e command to run so you can see 
the files in the directory before they're deleted. 

A d response initiates the deletion process. 

A q response aborts the command before action is taken. 

The directory to be deleted may include other directories 
which may themselves include other directories, and so forth. 
In this case, Deldir operates recursively (that is, it calls itself) 
so all lower- level directories are automatically deleted. The 
lower-level directories arc processed first. 

You must have correct access permission to delete all files 
and directories encountered. If not, Deldir will abort when 
it encounters the first file for which you don't have write 
permission. 
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The Deldir command automatically calls the Dir and Attr 
commands, so they must reside in the current execution 
directory. 



DIR 

DIR [e] [x] [directoryname or pathname] 

Displays a formatted list of file names in a directory. 

If no parameters are given, the current data directory is 
shown. If the x option is given, the current execution direc- 
tory is shown. If a full pathname of a directory is given, it is 
shown. Results are displayed on the standard output path. 

If the c option is included, each file's entire description is 
displayed: size, address, owner, permissions, date and time 
of last modification. 

Examples: 

di r dNTER] 

displays the current data directory. 



d i r x ( ENTER ) 
displays the current execution directory. 



dir x e (ENTER ) 

displays the entire description of all files in the current execu- 
tion directory. 

dir ♦ ♦ C ENTER) 

displays the parent of the current working directory - the 
directory immediately above it in the hierarchy. 



d i r n e w stuff CENTER] 
displays the newstuff directory 
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dir e TEXT-PROGRAMS (ENUR) 

displays the entire description of all files in the directory 
called TEST _ PROGRAMS. 



DISPLAY 



DISPLAY <hex> [...] 



Reads one or more hexadecimal numbers given as param- 
eters, converts them to ASCII characters, and writes them to 
the standard output. 

Display is commonly used to send special characters (such as 
cursor and screen control codes) to terminals and other I/O 
devices. 

Examples: 



display 0C >P (ENUR) 
reroutes "form reed'" — - hex OC — - to the printer. 



display 41 42 43 44 45 4G (SEWS) 
ABCDEF 

is an example of a command and the resulting output; 
ABCDKF are ASCII characters corresponding to hex 41 42 
43 44 45 46. 



DSAVE 

DSAVE [-opts] [devname] [directoryname or pathname] 

Backs-up or copies all files in one or more directories. 

Dsavc is unlike most other commands in that it does not 
directly affect the system. Instead, it generates a procedure 
file which you execute later to actually do the work. 
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When you run Dsavc, it writes copy commands to standard 
output to copy files from the current data directory on dev- 
name (the default is /DO) to the directory specified by diree- 
toryname or pathname. If you don't specify a directory name 
or pathname the copy is performed to the data directory that 
is the current directory at the time the Dsavc procedure file is 
executed. 

If Dsave encounters a directory file, it automatically includes 
Makdir and Chd commands in the output before generating 
copy commands for files in the subdirectory. Since Dsave is 
recursive in operation, the procedure file exactly replicates all 
levels of the file system from the current data directory down- 
ward (such a section of the file system is called a "subtree 11 ). 

If the current working directory happens to be the root direc- 
tory of the disk, Dsave creates a procedure file that backs up 
the entire disk file by file. This is useful when it's necessary 
to copy many files from diskettes formatted differently, or 
from floppy diskettes. 



Dsave options are: 
-b 

-b = pathname \ 



-m 



-suiteger 



Make output diskette a system 
diskette by using source disk- 
ette's OS9Boot file, if present 
Make output diskette a system 
diskette using pathname as 
source for the OS^Boot file 
Indent for directory levels 
Do not process directories be- 
low the current level 
Do not include Makdir com- 
mands in procedure file 
Set copy parameter to integer K 



Examples: 



chd /D2 (ENLERJ 

dsave /D2 >/D0/maK e copy CENTER) 

chd /Dl ( INTER] 

/D0/maKecopy [ENTER] 

The first command positions the user in /D/, the directory to 
be copied. Then Dsave makes a procedure file — actually a 
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directory - makccopy. The Chd command specifies that the 
copy is to be made on the the '1)1 director}, and the final 
command executes the procedure file. 



DUMP 



DUMP {filename or devname] 



Produces a formatted display of the physical data contents oi 
the path specified, which may be a diskette or any other I/O 
device. 

If you don't specify a filename, Dump uses the standard input 
path — the keyboard. Dump writes output to the standard 
output path — the video display. This command is commonly 
used to examine the contents of non-text files. 

Dump displays data 8 bytes to a line in both hexadecimal and 
ASCII character format. Data bytes that have non-displayable 
values are represented by periods in the character area. 

The addresses displayed on the dump are relative to the be- 
ginning of the file. Because memory modules are position- 
independent and stored on files exactly as they exist in 
memory, the addresses shown on the dump correspond to the 
relative load addresses of memory-module files. 

Examples: 



dump (ENTER) 

displays keyboard input in hex. Output is written to the video 
display. 

dump @/Dl 

The k (V/ ' svmbol causes OS-9 to treat the entire disk as a file. 
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ECHO 

ECHO text 



Sample Output: 



d u m p SYS/password > / P 



1 



3 4 5 6 7 



4 6 



Addr 89ABCDEF 



8 A C E 



0000 
0008 

0010 

0018 
0020 

0028 
0030 
0038 



2C2C302C3132382C 
2F44302F434D4453 
2C2E2C5348454C4C 
0D55534552312C2C 
312C3132382C2E2C 
2E2C5348454C4C0D 
55534552322C2C32 
2C3132382C2E2C2E 



* *0 .128 * 
/D0/CMDS 
*. .SHELL 
♦USERI t t 
1 1 128 * • * 

• .SHELL* 
USER2 t .2 
.128 ,* t* 



1 



3 4 5 S 7 







4 G 



Addr §_9_A_B_C_D_E_F_ 

2C5348454C4C0D55 
534552332C2C332C 
3132382C2E2C2E2C 
5348454C4C0D5553 
4552342C2C342C31 
32382C2E2C2E2C53 
48454C4C0D 



8 A C E 



0040 
0048 

0050 

0058 

00G0 

00G8 

0070 



>SHELL*U 
SER3 * *3 f 
128 t . t ♦ t 
SHELL,US 
ER4 t *£l> 1 
28 > ♦ . ♦ ,S 
HELL. 



The first column indicates the starting address. The next eight 
columns (01 through HF) display data hytes in hexadecimal 
format. The final column (0 through B) displays data byes in 
ASCII format. Non-ASCII displayable hytes are shown as 
periods, in the ASCII character display section. 



Hchoes entered text to the standard output path 

Hcho is typically used to generate messages in shell procedure 
files or to send an initialization character sequence to a ter- 
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minal. The text shouldn't include any of the punctuation char- 
acters used by the shell. 

Examples: 

echo HELLO, HOW'S IT GOING? 

prints the message on the screen. This example would be useful 
as a background task. 

echo >/P LISTING* OF PASSWORD FILE: 
list SYS/password >/P& 

8:003 

e o f 

prints the message - fisting of password file — to the printer 
and lists the file SYS/password to the printer as a background 
task. 

LISTING OF PASSWORD FILE 
t t$ tl28 ,/D0/CMDS , ♦ , SHELL 
LJSERi ft! ,128 , ♦ , . , SHELL 
USER2 t ,2 ,128 t. ,. t SHELL 
USERS t ,3 ,128 , • , . t SHELL 
U5ER4 t >a ,128 t* t. tSHELL 

Here is the example run* 

echo >/TERM **WARNING** DISK ABOUT 
TO BE SCRATCHED! (jNTfff) 

echoes the text to the console. 

echo >/P LISTING OF TRANSACTION 
FILE5 List Trans >/P& (WIS) 

combines two commands. The first echoes the entered text to 
the printer. The second (List) directs the contents of the trans 
file to the printer. 
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FORMAT 

FORMAT devname 



Physically initializes, verifies, and establishes an initial file 
structure on a diskette. All diskettes must be formatted before 
you can use them on an OS-9 system. 

The diskette to be formatted must NOT be write protected. 

The formatting process works this wax: 

1. Format physically initializes and sectors the diskette 
surface. 

2. Format reads back and verifies each sector. If a sector 
fails to verify after several attempts, it's excluded from the 
initial free space on the diskette. As the verification pro- 
ceeds, track numbers are displayed on the standard output 

device. 

}. The diskette allocation map. root director), and identifica- 
tion sector are written to the first tew sectors of track 
zero. These sectors must not he defective. 

Format will prompt for a diskette volume name, which can be 
up to }2 characters long and can include spaces or punctua- 
tion. (Later. \ou can use the Free command to displav the 
name. ) 

For step-by-step instructions on formatting, refer to (icitinx 
Started with OS-9. 
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FREE 



FREE [devname] 



Displays the number of unused 256-byte sectors on a device. 
These sectors are available for new files or tor expanding 
existing tiles. 

The device name you specify must be a disk drive. Free also 
displays the diskette's name, creation date, and cluster size. 
If you don't specify a device, drive is assumed. 

Data sectors are allocated in groups called "clusters". The 
number of sectors per cluster depends on the storage capacity 
and physical characteristics of the specific device. This means 
that small amounts of free space are divisible into fewer files. 
For example, if a given disk system uses 8 sectors per clus- 
ter, and a Free command shows 32 sectors free, a maximum 
of four new files could be created, even if each has only one 
cluster. 

Examples: 



free SNUB 

COLOR COMPUTER DISK created on: 

83/05/28 
Capacity: 830 sectors (i-sector 

clusters) 
15 Free sectors t largest block 

12 sectors 



f ree /Dl (E NTER] 

DATA DISK created on: 83/0G/1B 

Capacity : 830 sectors (i-sector 

clusters) 
445 Free sectors* largest block 

442 sectors 
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IDENT 

IDENT filename [-opts] 

Displays header information from OS-9 memory modules. 

Ident displays the module size, CRC bytes (with verification), 
and, for program and device driver modules, the execution 
offset and the permanent storage requirement bytes. Ident 
prints and interprets the type/language and attribute. revision 
bytes. Ident displays the byte immediately following the mod- 
ule name because most Mieroware-supplied modules set this 
byte to indicate the module edition. 

Ident displays all modules contained in a diskette file. 

Options are: 

-in Assumes that filename is a module in memory 

-v Does not verify module CRC 

-x 6 Assumes that filename is in execution 

directory 

-s Displays on a single line module information 

including edition byte (first byte after module 
name); type/language byte; module CRC; "." 
if CRC verifies, "V 1 * if it doesn't, a blank 
space if you use the ' L -v'" option; and module 
name. 

Examples: 



ident - m 1 d e n t CENTER) 

Header for: Ident 

Module sizes $ G C E #1742 

Module CRC: $G114F4 (Good) 

H d r parity: $ E 

Exec, off: $0235 #5G5 

Data size: $099C #24G0 

Edition: $06 #S 
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T*//La At/Ru $11 $81 

Pro? m o d t B 8 9 obj > r e - e n 

In the example. Hdr parity = header parity; Hxee. oil = 
execution offset; Data si/e = permanent storage require- 
ments; Edition - first byte after module name; Ty/La/ At/Rv 
= type/language attribute/revision; and Prog mod, 6809 obj, 
re-en — module type, language, attribute. 



i dent /D0/OS9boot 


-s center; 


o 


$E1 


$524CEB ♦ 


CCDisk 


82 


$F1 


$EDF046 ♦ 


00 


82 


$F1 


$699330 ♦ 


01 


82 


$F1 


$653603 ♦ 


D2 


82 


$F1 


$E155A8 ♦ 


03 


3 


$E1 


$0A6A0A ♦ 


CCI0 


83 


$F1 


$3EDF55 , 


TERM 


a 


$C1 


$600579 ♦ 


IOMan 


G 


$D1 


$C06CB6 ♦ 


RBF 


7 


$01 


$04D9ES . 


SCF 


5 


$C1 


$179500 ♦ 


S y s G o 


2 


$C1 


$7255DB ♦ 


C 1 o c K 


20 


$1 1 


$59ECC8 ♦ 


Shel 1 


o 


$E1 


$316E57 ♦ 


RS232 


83 


$F1 


$7BF6CE * 


Tl 


1 


$E1 


$-318E57 ♦ 


PRINTER 


83 


$F1 


$8080DF ♦ 


P 


3 


$01 


$5F72A5 ♦ 


Pi peHan 


*? 


$E1 


$552556 ♦ 


Piper 


80 


$F1 


$CC06AF ♦ 


Pipe 



Since the -s option appears in the command line. Ident dis- 
plays each module's information on a single line. In the first 
line of the output, for instance. I - edition byte (first byte 
after name); SCO - type/language byte; SA366DC = CRC 
value; , ~ OK CRC cheek; and OS9p2 ~ module name. 
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KILL 

KILL procID 



Aborts the process specified by its process ID number. 

The process to be aborted must have the same user ID as the 
user executing the command. (Use the Procs command to 
obtain the process ID numbers.) 

If a process is waiting tor I/O. it may not die until it com- 
pletes the current I/O operation. Therefore, if you Kill a 
process and the Procs command shows it still exists, it's 
probably waiting to receive a line of data from a terminal 
before it can die. 

Since this is a built-in shell command, it doesn't appear in the 
CMDS directory. 

Examples: 



Kill 5 (ENTER) 
kills the process with the ID number 5 

procs iENTERI 

User « ID pty Uate__ Mem P r 1 m a r / m o_'J_ u J_e 

2 active 2 Shell 

1 waiting 1 5 v s a o 

3 sleeping 20 Copy 

Kill 3 ENTERJ 
procs i ENTER! 



U ser » ID pti 



state Mem Primary m o d u 1 e 



ac t i i' i 

waitn 



Shell 



In this example, the user employs the Procs command to de- 
termine the ID number of the process to be killed, and finds 
that the number is 3. The Kill command kills the process. 
Then the user again employs Procs. this time to check 
whether the targeted process has died. Since it doesn't appear 
in the output, the user knows the process has been killed. 
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LINK 

LINK memory module name 

"Locks" a previously loaded module into memory. 

The link count of the module specified is incremented by one 
each time it is "linked/ ' Use the Unlink command to "un- 
lock" the module when you no longer need it. You must use 
the Load command prior to using Link. Modules that are not 
Linked in memory will not be included in the "Cobbler" 
()S9Boot file, if you use the Cobbler command. 

Examples: 



1 i n K edit (ENJER) 
locks the edit module into memory. 



LIST 

LIST filename [...] 



Lists the contents of a text file. 

This command copies text lines from the filename to the stan- 
dard output path. The program terminates upon reaching the 
end-of-file of the last input path. If more than one filename is 
specified, the first file will be copied to standard output, the 
second file will be copied next, and so forth. 

This command is most commonly used to examine or print 
text files. 

Examples: 



list /D0/startup >/P &= (ENTER) 

Lists the contents of the Startup file, with output directed to the 
printer. The ampersand tells OS-9 to make the printing job a 
concurrently executed task. 
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list /D1/USER5/ .document /D0/my f i le 
/D0/BQB/text(E NTER ) 

Lists l he contents of" three files. 

list /TERM >/P CENTER) 

Copies what you type at the keyboard to the printer. To go 
back to the standard output path — the video display — press 
[CLEAR) and (BREAK) simultaneously. 



b u Ud animals (ENTER) 
? cat ( ENTER) 
? cow ( ENTER ) 



do 5 ( ENTER ) 



? elephant ( ENTER) 

? bird ( INTER ] 

? fish (ENTER) 

? (ENTER) 

list animals ( ENTER ) 

cat 

c o w 

do * 

e 1 e p h a n t 

b i r d 

f i sh 



LOAD 



LOAD pathname 



Here the user employs Build to create a file called animals, 
and enters six items into it. The List command, with the file- 
name animals as a parameter, displays the contents of the 
new file. 



Loads modules from file into memory. 

The path specified is opened and one or more modules is read 
from it and loaded into memory. The names of the modules 
are added to the module directory. If a module is loaded that 
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has the same name and type as a module alreacK in memory, 
the module with the highest re\ision level is kept. 



Example: 








m d i 


r fENTER) 








M o d ule D 


irector y a t 


i3;3G"47 




OSS 


0S9p2 


INIT 




Boot 


CCDisK 


D0 




DI 


D2 


D3 




CCIO 


TERM 


IOMan 




RBF 


SCF 


S v s G o 




Clock 


Shell 


RS232 




Ti 


PRINTER 


P 




Pi p e M a n 


Piper 


Pipe 




Mdir 







load edit (ENTER] 
m d i r (ENTER) 

Module Directory at 1 3 : 3 7 s 1 <4 

053 0S3p2 INIT 

Boot CCDisK D0 

Di D2 D3 

CCIO TERM IOMan 

RBF SCF SysGo 

ClocK Shell RS232 

Tl PRINTER P 

PipeMan Piper Pipe 

M d i r Edit 

First, the Mdir command displays the names ai~ modules cur- 
rently resident in memory. Then the Load command loads the 
Edit module into memory. Mdir again lists the memory mod- 
ules, this time showing that Edit has successfully been added to 
memory. 
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LOGIN 

LOGIN 



Provides login security on timesharing systems. 

Login is automatically called by the timesharing monitor 
Tsmon, and can also be used after initial log-in to change a 
terminal's user. 

Login requests a user name and password, which it checks 
against a validation file. If the information is correct, the us- 
er's system priority, user ID, and working directories are set 
up according to information stored in the file, and the initial 
program — - usually shell — specified in the password file is 
executed. If the user can't supply a correct user name and 
password after three attempts, the process is aborted. 

The validation file is /DO/SYS/password. The file contains 
one or more variable-length text records, one for each user 
name. Each record has the following fields, delimited by 
commas: 

1. User name (up to 32 characters; may include 
spaces). If this field is empty, any name will match. 

2. Password (up to 32 characters; may include spaces). 
If this field is omitted, no password is required by 
the user whose record this is. 

3. User index (ID) number (from to 65535; is su- 
peruser). This number is used by the file security 
system, and as the system-wide user ID, to identify 
all processes initiated by the user. The system man- 
ager should assign a unique ID to each potential 
user. 

4. Initial process (CPU time) priority: 1-255. 

5. Pathlist of initial execution directory (usually /DO/ 
CMDS). 

6. Pathlist of initial data directory (the specific user's 
directory). 
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7. Name of initial program to execute (usually Shell). 
Don't use shell command lines, such as Dir or 
Deheck, as initial program names. 

Here's a sample validation file: 
,,0,128,/DO/CMDS,. .SHELL 

USER 1„ 1,128 SHELL 

USER2,,2,128 SHELL 

USER3,,3,128 SHELL 

USER4,,4,128 SHELL 

To use the Lo^in command, enter: 



la Sin dNTER) 

This will cause prompts for the user's name and (optionally) 
password to be displayed. If they're answered correctly, the 
user is logged into the system. Login initializes the user num- 
ber, working execution directory, and working data directory, 
and executes the initial program specified by the Password 
file. It also displays the date, time and process number 
(which is not the same as the user ID). 

If the shell from which Login was called will not be needed 
again, you can discard it by using the Ex command to start 
the Login command. For example: 

ex 1 o $ i r. CENTER) 

To edit Password and add users to the system, use the OS-9 
text editor. 

Logging Off the system 

To log off the system, terminates the initial program specified 
in the password file. For most programs (including shell) this 
involves typing an end-of-file character as the first character 
on a line. (CLEAR ) and C6REAK] , pressed simultaneously, signal 
end-of-file and log you off. 

Displaying a "Message-of-the-Day" 

A file named Motd, in the SYS directory, will cause Login to 
display its contents on the user's terminal after successful 
login. (This file isn't necessary for Login to operate.) 
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Example: 

loain INTER) 

OS-9 Level I Timesharing System Verison 1.2 83/12/04 
13:02:22 



User name?: super user (ENTER) 
Password: secret CENTER) 

Process #07 losfSed 83/12/04 

13:03:00 
Welcome ! 

To edit Motd, use the OS-9 Text Editor. 



MAKDIR 



MAKDIR pathname or directory name 



Creates a new directory according to the pathname given. The 
pathname must refer to a parent directory for which the user 
has write permission. 

The new directory is initialized and at first does not contain 
files except for the "." and ".." pointers to its parent direc- 
tory and itself, respectively. All access permissions are en- 
abled (except sharablc). 

It's customary, but not mandatory, to capitalize directory 
names. 

Examples: 



makdir /D 1 /STEYE/ PRO JECT dBHH) 
creates a directory by using its full pathname from the root. 



makdir DATAFILES (ENTER) 

creates a directory called DATAFILES within the current 
working directory, 
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MDIR 

MDIR [e] 



makdir ♦♦/5AUEFILES (INTER) 

creates a directory called /SAVHFILES in the parent 
directory. 



Displays the present module names in the system module 
directory, that is all modules currently resident in memory. 

If you use the e option, you'll see a full listing of the physical 
address, size, type, revision level, reentrant attribute, user 
count, and name of each module. All numbers shown are in 
hexadecimal. 

Examples: 



m d i r CENTER! 

Module Directory at 14:44::35 



0S9 


0SS)p2 


INIT 


Boot 


CCDisk 


D0 


01 


D2 


D3 


CCIO 


TERM 


IOMan 


Rr3F 


SCF 


S Y 5 3 


Clack 


Shell 


RS232 


Tl 


PRINTER 


P 


P i p e M a n 


Piper 


Pipe 


Mdi r 
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wdi r e CENTER) 

Module Directory at 10:55:04 



ADDR 


SIZE 


TY 


RU 


AT 


UC 


NAME 


C305 


2F 


Fl 


1 


r 




D0 


F053 


7E8 


CI 


1 


r 




0S9 


F852 


4F4 


CI 


1 


r 




0S9P2 


FD4S 


2E 


C0 


1 


r 




INIT 


C3G3 


798 


El 


- 1 


r 


i 


CCIO 


CAFB 


38 


Fi 


1 


r 


*~? 


TERM 



This is a partial listing of all the attributes of the modules in 
memory after executing the above command. 

Warning: Many of the modules by Mdir are OS-9 system 
modules and executable as programs. Always check the mod- 
ule type code before running a module if you aren't familiar 
with it! 



MERGE 



MERGE [filename] [...] 



Copies multiple input files specified by the parameter(s) to 
the standard output path. 

Merge is commonly used to combine several files into a sin- 
gle output file. Data is copied in the order the filenames are 
given. Merge does no output line editing (such as automatic 
line feed). The standard output is generally redirected to a file 
or device. 

Merge can be used to append or copy any type or mixture, of 
files to another device. 

Examples: 

dier^e filel f i 1 e 2 f i 1 e 3 f i 1 e 4 
> c o m b i n e d ♦ f i 1 e CENTER] 
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merges the four files specified into a new file called com- 
bined. file and sends the results directly to the new file, in- 
stead of to the video display. 

m e r sf e compile* list a s m ♦ 1 i s t > / P 



(ENUR) 

merges the two files specified and sends the output to the 
printer. 



MFREE 

MFREE 



Displays a list of memory areas not presently in use and 
therefore available for assignment, 

Displays the address and size of each free memory block. The 
size is given as the number of 256-byte pages. This informa- 
tion is useful to detect and correct memory fragmentation. 

Example: 



mfree INTER) 

_ Add res s _ 

E00-B1FF 
B400-B4FF 



pa^es 

164 
1 



OS9GEN 



OS9Gen devname 



Total pa^es free = 1 G5 
Graphics Memory Not Allocated 



Creates and links the OS9Boot file required on any disk from 
which OS -9 is to be bootstrapped, 
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OS9Gen is used to add modules to an existing boot, or to 
create an entirely new boot file. (If you want an exact copy of 
the existing OS9Boot file, use the Cobbler command in- 
stead). 

The name of the device on which the OS9Boot file is to be 
installed is passed to OS9Gen as a command line parameter. 
OS9Gen then creates a working file called tempboot on the 
device specified. Next it reads file names (pathnames) from 
its standard input, one pathname per line. Every file named is 
opened and copied to tempboot. This is repeated until an end- 
of-file marker or a blank line is reached on OS9Gen's stan- 
dard input. All boot files must contain the OS-9 component 
modules listed in section 5.1. 

After all input files are copied to tempboot, the old OS9Boot 
file, if present, is deleted. Tempboot is then renamed 
OS9Boot, and its starting address and size are linked in the 
disk's Identification Sector (LSN 0) for use by the OS-9 boot- 
strap firmware. 

Note: Any OS9Boot file must be stored in physically 
contiguous sectors. Therefore, OS9Gen is normally 
used on a freshly formatted disk. If the OS 9 Boot file is 
fragmented, OS9Gen prints a warning message indicat- 
ing that the disk can't be used to bootstrap OS-9. 

The list of file names given to OS9Gen can be entered from a 
keyboard, or OS9Gen's standard input can be redirected to a 
text file containing a list of file names. If you enter names 
manually, no prompts are given, and you enter the end-of-file 
marker (usually (CLEAR) (BREAK) or a blank line) after the line 
containing the last filename. 

Examples: 

To manually install a boot file on device /Dl which is an 
exact copy of the OS9Boot file on device /DO. 



0S9Gen /Dl (ENTER) 



/D0/OS3Ooot (ENTER) 
(CLEAR) (BREAK) 
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The first command line runs OS9Gen. The second enters the 
name of the file to be installed, and the third enters an end- 
of-file marker. 

To manually install a boot file on device /Dl which is a copy 
of the OS9Boot file on device /DO with the addition of mod- 
ules stored in the files /DO/tape. driver and /D2/video. driver: 



0S9Gen /Dl (ENTER) 
/D0/OS9Boot (ENTER) 
/D0/tape .d rive r (ENTlB) 



/D2/uideo ♦ driver CENTER) 



The first command line runs OS9Gen. The second enters the 
main boot file name. The third and fourth enter the names of 
the two files to be added, and the fifth enters and end-of-file 
marker. 

To do exactly what the previous example does, but to do it 
automatically by redirecting the standard input for OS9Gen; 



build /D0/hootlist (ENTER) 

? /D0/OS9Boot (ENTER) 

? /D0/tape«driuer (ENTER) 

? /D2/video # driuer (ENTlR) 

? (ENTER) 

0S9Gen /Dl < /D0/boo 1 1 i s t (ENTER) 

The first command line uses Build to create a file called 
Bootlist. The next three lines enter the names of the three 
files within Bootlist. The fifth line terminates Build, and the 
sixth and final line runs OS9Gen with input redirected from 
the new Bootlist file. 



PRINTERR 

PRINTERR 
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Prints full -text error messages. 

This command replaces OS-9 error printing routine (F$Perr), 
which prints only error code numbers, with a routine that 



PROCS 

PROCS [e] 



reads and displays textual error messages from the file /DO/ 
SYS/errmsg. Printerr's effect is system-wide. 

A standard error message file is supplied with OS-9. The user 
or editor can replace or modify this file, which is a normal 
text file with variable-length lines. 

Each error message line begins with the error number code 
(in ASCII characters), a delimiter, and the error message text. 
The error messages need not be in any particular order. De- 
limiters are spaces or any character numerically lower than 
$20. Any line with delimiter as its first character is con- 
sidered to be a continuation of the previous linc(s); this per- 
mits multi-line error messages. 

Warning: Once the Printerr command has been used, it can 
not be undone. Once installed, DO NOT unlink the Printerr 
module. Printerr uses the current user's stack for an I/O buf- 
fer, so users are encouraged to reserve reasonably large 
stacks. The only way to effectively Unlink Printerr is to re- 
boot or reset the machine nxiiii> OS-9. 

Example: 



printerr CENTER] 

Note: The errmsg file must be on /DO. 



Displays a list of processes running on the system. 

Normally lists only proeesses having the user's ID. If the e 
option is given, Procs lists processes of all users. The display 
is a "snapshot" taken at the instant the command is executed: 
processes can switch states rapidly, usually many times per 
second. 

Procs shows the user and process ID numbers, priority, state 
(process status), memory size (in 256 byte pages), primary 
program module, and standard input path. 
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Example: 



PWD 
PXD 

PWD 
PXD 



procs e dSHS) 

User « _ I d p t y state_ Mem Primary jT|_o_dj.d_e_ 

2 active 2 Shell 

1 waiting 1 S v s G o 
i 3 1 waiting 2 T s m o n 

1 a 1 wait in* 4 Shell 

1 5 1 active 64 BASIC09 



Pwd shows the path from the root directory to the current 
data directory. Pxd shows the path to the current execution 
directory. 

OS-9 programs use both commands to track the actual physi- 
cal location of files. People use it when they get 'Most' 1 in the 
file system. Both commands, show a path "home". 

Examples: 

chd /Dl/STEUE/TEXTF I LES /MANUALS 
(ENTER) 

using a full pathname, Chd changes the user's current data 
directory, so the user is now in the MANUALS directory. 



pwd (ENTER) 

/Dl/STEUE/TEXTF I LES /MANUALS 

Pwd shows the full path to the working directory. 



chd ♦ ♦ IRHR) 
pud (ENTER) 

/Dl/STEUE/TEXTFILES 
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The user * 'backs up" one level in the directory hierarchy, and 
then asks what the working directory is. Pwd shows that it is 
now TEXTFILES. 

c h d ♦ ♦ CENTER) 



pwd [ENTER] 

/Di/STEUE 

The user again backs up, and sees, with Pwd, that the work- 
ing directory is now STEVE. 



pxd (ENTER) 

/D0/CMDS 

The user sees that the current execution directory is CMDS. 



RENAME 



RENAME filename new filename 



Gives the file or directory specified in the path list a new 
name. 

The user must have write permission for the file in order to 
change its name. It's not possible to change the names of 
devices, '\'\ or "..". 

Examples: 

r e ri a m e blue purple CENTER) 
gives the new name purple to the file formerly called blue. 



rename /D3/user9/test temp (ENTER) 
gives the new name temp to the file formerly called /test. 



di r (ENTER) 

Directory of ♦ 1G;22s53 
m y f i 1 e animals 



rename animals cars [ENTER ) 
di r CENTER) 
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Directory of ♦ 16:23:22 
mv f i 1 e cars 

In this sequence, the user employs Dir to see the name of 
files in the current data directory. Then Renames changes 
name of file called animals to the new name cars. Another 
Dir command shows that the name has been changed. 



SAVE 



SAVE filename modname [...] 



Creates a new file and writes a copy of the memory mod- 
ule(s) specified onto the file. 

The module namc(s) must exist in the module directory when 
saved. Save gives the new file access permissions for all 
modes except public write. 

Note: Save's default directory is the current data direc- 
tory. Executable modules should generally be saved in 
the default execution directory. 

Examples: 

s a u e D0/CMD5/workcount w c o u n t 

saves the wcount module into the newly created file called 
/workcount in the /DO/CMDS. 

saue /Dl/ roath_pack add sub m u 1 d i v 

saves four modules (add, sub, mul and div) into the new file 
called /D I/math _ pack 



SETIME 



SETIME [yy/mm/dd/hh:mm:ss] 



Sets the system date and time, then activates the real time 
clock. 
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The date and time can be entered as parameters. If no param- 
eters are given, Setime will issue a prompt. Numbers are one- 
or two-decimal digits using space, colon, semicolon or slash 
delimiters. OS-9 system time uses the 24-hour clock, on 
which, for instance, 1520 is 3:20 P.M. 

Important Note: This command must be executed be- 
fore OS-9 can perform multitasking operations. 

Examples: 



setime 83 t 1 2 1 1 5 * 1 545 (ENTER! 
sets the date and time to December 15, 1983, 3:45 P.M. 



setime 83/12/15 15/45/00 CENTER) 

sets the same date in a slightly different, but equally accept- 
able format. 



SETPR 

SETPR procID number 

Changes the CPU priority of a process. 



The process priority number is a decimal number in the range 
— the lowest — - to 255. If you need information about 
the process ID number and current priority, use the Procs 
command. 

You can use Setpr only on processes which have your ID 
number on them. 

Note: This command does not appear in the Cmds 
directory because it is built into the shell. 

Examples: 



setpr 8 250 CENTER) 

sets or changes process #8 to priority 250 

procs ( INTER ) 
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User 



SHELL 

SHELL arglist 



ID 
3 



state 



Mem Primary module 



waiting 

waiti n g 
w a 1 t i n g 



Shell <TERM 
Shell <TERM 
Sysgo <TERM 



setpr 3 128 (INUE) 
pfqcs (INTER) 



User 



_ID 
3 



pt > 
12E 



state 



Mem Primary module 



active 2 
waiting 2 
waiting 1 



Shell <TERM 
Shell (TERM 
Sysgo <TERM 



The Procs command displays process ID numbers and other 
information. The next command — Setpr 3 128 — sets pro- 
cess #3 to a priority of 128. The final command checks to 
make sure the change has been made. 



The shell is OS-9's command interpreter program. It reads 
data from its standard input path (the keyboard or a file), and 
interprets the data as a sequence of commands. The basic 
function of the shell is to initiate and control execution of 
other OS -9 programs. 

The shell reads and interprets one text line at a time from the 
standard input path. After interpretation of each line, it reads 
another until it reaches an end-of-file marker at which time 
it terminates itself. A special case occurs when the shell is 
called from another program. In that case, it takes the ar- 
gument list as its first line of input. If this command line 
consists of "built-in" 1 commands only, the shell reads and 
processes more lines. Otherwise control returns to the calling 
program after the single command line is processed. 

The rest of this description is a technical specification of the 
shell syntax. Use of the shell is described fully earlier in this 
manual. 



106 



Shell Input Line Formal Syntax: 



<pgm line> : = <pgm> {<pgm>} 

<pgm> := [<params>] [<namc> [<modif>] 

[pgm params>] [<modif>] 

{<sep>} 

Program Specifications: 

<name> : = < module name> 
<pathname> 
( <pgm list> ) 



Parameters: 

<params> 

<delim> 

<param> 



= <param> { <delim> <param> } 

= space or comma characters 

= ex <name> [<modif>] chain to program 

specified 

= chd <pathlist> change working 

directory 

= kill <proclD> send abort signal to 

process 

= sctpr<procID> <pty> change process 

priority 

change execution 
directory 

wait for any process 
to die 

turn OS9: prompting 
on 

turn prompting off 
echo input lines to 
std output 
don't echo input 
lines 

don't abort on error 
abort on error 
comment line: not 
processed 



: = chx <pathname> 
: = w 

■= P 

:= -p 

:= t 

:= -I 



= x 

- * <text> 
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<sep> 



:= & 



<cr> 



sequential execution 
separator 
concurrent execu- 
tion separator 
pipeline separator 
end-of-line (se- 
quential execution 
separator) 



Modifiers: 

<modif> 

<mod> 



<mod> { <delim> <mod> 
< <pathname> 
> <pathname> 
>> <pathname> 

# < integer > 

# <integer> K 



redirect standard 

input 

redirect standard 

output 

redirect standard 

error output 

set process memory 

size in pages 

set program memory 

size in 1 K 

increments 



SLEEP 



SLEEP tick count 



Puts the process to " sleep 1 ' for a number of clock ticks. 

Tick count may be any number 1 through 65535. If any num- 
ber larger than 65535 is given for tick count, the number will 
be reduced by mod 65535. For example, 65536 would be 
reduced to 0; as would all multiples of 65536. A tick count of 
95000 would be reduced to an actual tick count of 29464. 

Sleep is generally used to generate time delays or to "break- 
up" CPU-intensive jobs. The duration of a tick is 16.66 
milliseconds. 
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A tick count of 1 causes the process to "give up" its current 
time slice. A tick count of zero causes the process to sleep 
indefinitely (the process is usually awakened by a signal). 

Example: 

sleep 25 (ENTER) 

puts the process ' k to sleep' 1 for 25 ticks. . .4 1 6.50 
milliseconds. 

list startup SYS/wiotd nothing & 

sleep 

&:004 

setime </TERM 

HELCOME TO COLOR COMPUTER OS-9 

-004 
ERROR #21G 

0S3: 

The. List command starts running as a child process invoked 
from shell, and is run as background task. The Sleep 
command then puts shell to sleep indefinitely. When List 
eventually encounters the file nothing, which doesn't exist, it 
terminates, and sends a signal (the error status), which wakes 
up shell. 

It's important to note, that if the error hadn't occurred, shell 
would have slept forever. (The keyboard is not read while the 
shell sleeps.) The only way out, would be to re-boot. 



TEE 

TEE pathname or devname [...] 

Copies standard input to multiple outputs. 

Tee is a filter that copies all text lines from its standard input 
path and also to any number of additional output paths whose 
names are given as parameters. 
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The example below uses a pipeline and Tee to send the out- 
put listing of the Dir command simultaneously to the 
terminal, the printer, and a disk file: 

Examples: 

dir e ! tee / P /D0/dir»listin3 

Here, a pipeline takes the output of the Dir e command and 
sends it to the terminal and lee. Tee in turn sends the output 
along to the printer and to a file called /DO/dir. listing. 

asm p £ m ♦ s r c 1 ! tee p 4 m ♦ 1 i s t / P 



1ENIER) 

In this example, the pipeline and Tee send the output of an 
assembler listing to a file (pgm.Iist) and to the printer. 

ECHO WARNING SYSTEM DOWN IN 
10 MINUTES ! tee /Tl (ENTER) 

Here, a message is broadcast to the terminal. 



TMODE 



TMODE [.pathnum] [paramlist] [...] 



Displays or changes the operating parameters of the user's 
terminal. 

You can specify any number of parameters from the list be- 
low, separating them by spaces or commas. If you don't 
specify parameters, the output will be current Tmode status. 

You can also use a period and a number to specify the path- 
number to be affected. If you don't specify any, Tmode 
affects the standard input path. 
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Note: If this command is used in a shell procedure file, 
you must use the parameter, .pathnum to specify one of 
the standard output paths (0, 1, or 2) to change the 
terminal's operating characteristics. The change will re- 
main in effect until the path is closed. To effect a 
permanent change to a device characteristic, the device 
descriptor must be changed. 

This command can work only if a path to the file/device has 
already been opened. You may alter the device descriptor to 
set a device's initial operating parameter (see the OS-9 Tech- 
nical Information manual). 

upc Upper-case only. Lower-case characters are 

automatically converted to upper-case. 

-upc Upper-case and lower case characters 

permitted. 

bsb Erase on backspace: backspace characters 

echoed as a backspace-space-backspace se- 
quence (default). 

-bsb No erase on backspace: echoes single back- 

space only. 

bsl Backspace over line: lines are "deleted" by 

sending backspace-space-backspace sequences 
to erase the same line (for video terminals) 
(default). 

-bsl No backspace over line: lines are "deleted" by 

printing a "new line 11 sequence (for hard-copy 
terminals). 

echo Input characters "echoed" back to terminal 

(default). 

-echo No echo. 

If Auto line feed on: line feeds automatically 

echoed to terminal on input and output carriage 
returns (default). 

-If Auto line feed off. 
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pause Screen pause on: output suspended upon full screen. 
Sec pag parameter for definition of screen 
size. Resume output by typing any key. 

-pause Screen pause mode off. 

null = n Set null count: number of null ($00) characters 

transmitted after carnage returns for return de- 
lay. The number is decimal. Default = 0. 

pag = n Set video display page, length to n (decimal) 

lines. Used for "pause" mode, see above. 

bsp^h Set input backspace character. Numeric value 

of character in hexadecimal. Default = 08. 

bse^h Set output backspace character. Numeric value 

of character in hexadecimal. Default = 08. 

del — h Set input delete line character. Numeric value 

of character in hexadecimal. Default = 18. 

bell = h Set bell (alert) output character. Numeric value 

of character in hexadecimal. Default = 07. 

eor=h Set end-of-record (carnage return) input char- 

acter". Numeric value of character in hexa- 
decimal. Default = 0D. 

cof=h Set end-of-file input character. Numeric value 

character in hexadecimal. Default = IB. 

type = h ACIA initialization value: sets parity, word 

size, and so forth. Value in hexadecimal. De- 
fault - 00. 

reprint = h Reprint line character. Numeric value of char- 
acter in hexadecimal. 

dup = h Duplicate last input line character. Numeric 

value of character in hexadecimal. 

psc = h Pause character. Numeric value of character in 

hexadecimal. 

abort = h Abort character (normally CONTROL C). 

Numeric value of character in hexadecimal. 
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quit = h Quit character (normally CONTROL L). 

Numeric value of character in hexadecimal. 

baud = d Set baud rate Tor software-controllable inter- 

lace. Numeric code for baud rate: 0=110 
1-300 2 = 600 3=1200 4 = 2400 5 = 4800 
6 = 9600 7= 19200 

Examples: 

tiriode - u p c If n u 1 1 = 4 p a u s e CENTER) 

t m o d e p a a = 2 4 pause b s 1 -echo 
bsp = 8 ( ENTER) 

Note: If you use Tmode in a procedure file. It's neces- 
sary to specify one of the standard output paths (.1 or 
.2), since the shell's standard input path will have been 
redirected to the diskette file. (Tmode can be used on 
SCFMAN-type devices only.) 

Example: 



tmode ♦ 1 pa 3 = 24 CENTER) 
This sets line/page on standard output. 



TSMON 

TSMON [devname] 



Supervises idle terminals and initiates the login sequence in 
timesharing applications. 

If you specify a device name, Tsmon opens standard I/O 
paths for the device. When you enter a carriage return, 
Tsmon automatically calls the Login command. If the login 
fails because the user can't supply a valid user name or pass- 
word, control returns to Tsmon. 

Note: The Login command and its password file must 
be present for Tsmon to work correctly (see the Login 
command description). 
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Logging Off the System 

Most programs will terminate when you enter an end-of-file 
marker ((CLEAR) (BREAK] ) as the first character on a command 
line. This will log you off the system and return to Tsmon 
which will run Login again. 

Examples: 



tsmon /T1&: (ffiffi) 

&:005 

This will activate /TK but must be run concurrently in order 
to keep /TERM active. 



UNLINK 



UNLINK modname [...] 



Tells OS-9 that the memory modulc(s) named are no longer 
needed by the user. 

OS-9 may (or may not) destroy the modules and reassign 
their memory depending on whether the module is in use by 
other processes. 

It's good practice to unload modules whenever possible to 
make most efficient use of available memory resources. Mod- 
ules that have been Loaded and Linked may have to be Un- 
linked twice to remove them from memory. 

Warning: Never attempt to unlink a module you didn't load 
or link. 

Examples: 



unlink plml p<fto5 p$n\3S (ENTER] 
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VERIFY 

VERIFY [u] 



Unlinks the three modules specified, 
m d i r CENTER] 

Module Directory at 11:26:22 



OSS 


05Sp2G 


INIT 


Boot 


CCDisk 


D0 


Di 


D2 


D3 


CCIO 


TERM 


IOMan 


RDF 


SCF 


S/sGo 


Clock 


Shel 1 


RS232 


Tl 


PRINTER 


P 


Pipetlan 


Piper 


Pipe 


Mdi r 


Edit 




u n link edit 


(ENTLRJ 




m d i r CENTER) 






Module D 


irectorv at 


11:27:2 


OSS 


0S9p2 


INIT 


Boot 


CCDisk 


D0 


Dl 


D2 


D3 


CCIO 


TERM 


IOMan 


RBF 


SCF 


S i /sGo 


Clock 


Shell 


RS232 


Tl 


PRINTER 


P 


P i p e M a n 


Piper 


Pipe 


MDi r 







In this sequence, the Mdir command displays modules in 
memory. The next command specifies that the edit module be 
unlinked, and the output of the final command — Mdir — 
shows that the unlinking has been successful: edit no longer 
appears on the list. 



Checks whether module header parity and CRC value of one 
or more modules on a file {standard input) are correct. 
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Module(s) arc read from standard input, output is sent to stan- 
dard output, and messages are sent to the standard error path. 

Verify is dependent on the (<), input redireetion command. 
If you fail to use the (<), redirection symbol, the Verify 
program will cause the system to lock. It is always necessary 
to redirect the input path. It is usually necessary to redirect 
the output and the error path. 

If you use the u (update) option, the module(s) are copied to 
the standard output path with the module's header parity and 
CRC values replaced with verify* s computed values. You see 
a message indicating whether the module's values match 
those computed by Verify. Verify, with the update option, 
will not set the execute flag in the file attributes. Use the Attr 
command to do this. 

If you don't use the option, the module isn't copied to stan- 
dard output. Verify simply displays a message indicating 
whether the module's header parity and CRC match those 
computed by Verify. 

Note: Verify does not turn on execute flag or update 
file. Use Attr. 

verify u < /D0/CMDS/ e d i t >/D0/CMDS/ 
newedit CENTER ) 

because the u option is used the edit module is copied to a 
new module, newedit, with the header parity and CRC values 
replaced with verify* s computed values. 

uerify <EDIT >NEWEDIT (INTER} 

Module's header parity is correct* 
Calculated CRC matches module's* 

The program checks the edit module, and directs program 
output to a file called newedit. Since the u option wasn't 
specified. Verify simply displays a summary message. 

u e r i f y < my p r o $ r a m 2 (E NTER] 

Module's header parity is correct* 
Calculated CRC m a t c h e s module's* 
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Checks the myprogram2 module. Since there's no u in the 
command line, the module isn't copied to standard output. 
Instead, a simple message is displayed. 



XMODE 



XMODE devname [paramlist] 



Displays or changes the initialization parameters of any SCF- 
type device such as the video display, printer, RS-232 port, 
and others. 

Common uses include changing baud rates and control key 
definitions. 

Xmode is similar to the Tmode command, but there are dif- 
ferences. Tmode operates only on open paths, so its effect is 
temporary. Xmode actually updates the device descriptor so 
the change persists as long as the computer is running, even 
if paths to the device are repeatedly opened and closed. 

If Xmode is used to change parameter(s) and the Cobbler 
program is used to make a new system disk or re-write sys- 
tem tracks on the current system disk, the changed parameter 
is permanently reflected on the new system disk. 

Xmode requires that you specify a device name. If you don't 
specify parameters, the present values for each parameter are 
displayed. You can use any number of parameters separating 
them by spaces or commas. 

XMODE parameter names: 

upc Upper-case only. Lower-case characters are 

automatically converted to upper-case. 

-upc Upper-case and lower case characters permit- 

ted, (default) 

bsb Hrase on backspace: backspace characters 

echoed as a backspace-space-backspace se- 
quence (default). 
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-bsb No erase on backspace: echoes single back- 

space only. 

bsl Backspace over line. Lines are "deleted" by 

sending backspace-space-backspace sequences 
to erase the same line (for video terminals) 
(default). 

-bsl No backspace over line. Lines arc "deleted" 

by printing a "new line 1 ' sequence (for hard- 
copy terminals). 

echo Input characters "echoed" back to terminal 

(default). 

-echo No echo'. 

If Auto line feed on. Line feeds are automatically 

echoed to terminal on input and output carriage 
returns (default). 

-If Auto line feed off. 

pause Screen pause on: Output suspended upon full screen. 
See pag parameter for definition of screen 
size. Resume output by typing any key. 

-pause Screen pause mode off. 

null = n Set null count. Number of null ($00) charac- 

ters are transmitted after carriage returns for 
return delay. The number is decimal. Default 
- 0. 

pag = n Set video display page length to n (decimal) 

lines. Used for "pause" mode, see above. 

bsp = h Set input backspace character. Numeric value 

of character in hexadecimal. Default = 08. 

bse = h Set output backspace character. Numeric value 

of character in hexadecimal. Default = 08. 

del = h Set input delete line character. Numeric value 

of character in hexadecimal. Default — 18. 
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bell = h Set bell (alert) output character. Numeric value 

of character in hexadecimal. Default = 07. 

eor = h Set end-of-record (carriage return) input char- 

acter. Numeric value of character in hexa- 
decimal. Default = 0D. 

eof-h Set end-of-file input character. Numeric value 

character in hexadecimal. Default = IB. 

type = h ACIA initialization value: sets parity, word 

size, and so forth. Value in hexadecimal. De- 
fault = 15. 

reprint = h Reprint line character. Numeric value of char- 
acter in hexadecimal. 

dup = h Duplicate last input line character. Numeric 

value of character in hexadecimal. 

psc = h Pause character. Numeric value of character in 

hexadecimal. 

abort = h Abort character (normally CONTROL C). 

Numeric value of character in hexadecimal. 

quit = h Quit character (normally CONTROL E). 

Numeric value of character in hexadecimal. 

baud = d Set baud rate for software-controllable inter- 

face. Numeric code for baud rate: 0=110 
1-300 2 = 600 3=1200 4 = 2400 5 = 4800 
6 = 9600 7 = 19200 

Examples: 

x m o d e /TERM -upc If n u 1 1 = a b s e = 1 F 



pause CENTER] 
xmode / T 1 p a 3 = 2 4 pause b s 1 -echo 



bsp = 8 (ENTER) 



xmode /P baud = 3 -If CENTER) 
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Appendix A/Error Codes 



The error codes are shown in both hexadecimal (first column) 
and decimal (second column). Error codes other than those 
listed are generated by programming languages or user 
programs. 



OS-9 Error Codes 



HEX DEC 

$02 002 

$03 003 

$C8 200 

$C9 201 

$CA 202 

$CB 203 

$CC 204 

$CD 205 

SCR 206 



KEYBOARD INTERRUPT — The user 
used (BREAK) to abort a task that was cur- 
rently being executed. 

KEYBOARD INTERRUPT — The user 



used (SHIFT) CBREAK) to cause the task to be 
executed as a background task with no 
video display, or to abort the task. 

PATH TABLE FULL — The file can't be 
opened because the system path table is cur- 
rently full. 

ILLEGAL PATH NUMBER — Number 
too large, or for non-existent path. 

INTERRUPT POLLING TABLE FULL 

ILLEGAL MODE — Attempt to perform 
I/O function of which the device or file is 
incapable. 



DEVICE TABLE FULL 

another device. 



Can't add 



ILLEGAL MODULE HEADER — Module 
not loaded because its sync code, header 
parity, or CRC is incorrect. 

MODULE DIRECTORY FULL — Can't 

add another module. 
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SCF 207 MEMORY FULL — Not enough con- 

tiguous RAM free. 

SDO 208 ILLEGAL SERVICE REQUEST — System 

call had an illegal code number. 

SD1 209 MODULE BUSY — Non-sharable module 

is in use by another process. 

$D2 210 BOUNDARY ERROR — Memory alloca- 

tion or deallocation request not on page 
boundary. 

$D3 211 END-OF-FILE — End-of-fiie encountered 

on read. 

SD4 212 RETURNING NON- ALLOCATED MEM- 

ORY — Attempted to deallocate memory 
not previously assigned. 

$D5 213 NON-EXISTING SEGMENT — Device 

has damaged file structure. 

$D6 214 NO PERMISSION — File or device attri- 

butes don't permit access requested. 

$D7 215 BAD PATHNAME — Syntax error in path- 

list, illegal character, for instance. 

$D8 216 PATH NAME NOT FOUND — Can't find 

path list spec i lied. 

$D9 217 SEGMENT LIST FULL — File is too frag- 

mented to be expanded further. 

$DA 218 FILE ALREADY EXISTS — Filename 
already appears in current directory. 

$DD 219 ILLEGAL BLOCK ADDRESS — - Device's 
file structure had been damaged. 

$DF 223 SUICIDE ATTEMPT — Request to return 

memory where your stack is located. 

$E0 224 ILLEGAL PROCESS NUMBER — No 
such process exists. 
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$E2 226 NO CHILDREN — Can't wait because pro- 
cess has no children. 

$E3 227 ILLEGAL SWI CODE — Must be 1 to 3. 

$E4 228 PROCESS ABORTED — Process aborted 
by signal code 2. 

$E5 229 PROCESS TABLE FULL — Can't fork 
now. 

$E6 230 ILLEGAL PARAMETER AREA — High 

and low bounds passed in fork call are 
incorrect. 

$E7 231 KNOWN MODULE — For internal use 

only. 

$E8 232 INCORRECT MODULE CRC — Module 
has bad CRC value. 

$E9 233 SIGNAL ERROR — Receiving process has 
previous unprocessed signal pending. 

$EA 234 NON-EXISTENT MODULE — Unable to 

locate module. 

$EB 235 BAD NAME — Illegal name syntax. 

$ED 237 RAM FULL — No free system RAM avail- 

able at this time. 

SEE 238 UNKNOWN PROCESS ID — Incorrect 

process ID number. 

SEF 239 NO TASK NUMBER AVAILABLE — All 

task numbers in use. 



Device Driver Errors 



The following error codes are generated by I/O device driv- 
ers, and are somewhat hardware-dependent. Consult manu- 
facturer's hardware manual for more details. 
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$F0 240 UNIT ERROR — Device unit doesn't exist. 

$F1 241 SECTOR ERROR — Sector number is out 

of range. 

$F2 242 WRITE PROTECT — Device is write- 
protected. 

$F3 243 CRC ERROR — CRC error on read or 
write verify. 

SF4 244 READ ERROR — Data transfer error dur- 
ing disk read operation, or SCF (terminal) 
input buffer overrun. 

$F5 245 WRITE ERROR — Hardware error during 
disk write operation. 

SF6 246 NOT READY — Device has "not ready" 
status. 

$F7 247 SEEK ERROR — Physical seek to non- 
existent sector. 

$F8 248 MEDIA FULL — Insufficient free space on 

media. 

$F9 249 WRONG TYPE — Attempt to read incom- 
patible media (for instance attempt to read 
double-side disk on single-side drive), 

$FA 250 DEVICE BUSY — Non-sharable device is 
in use. 

$FB 25 1 DISK ID CHANGE — Media was changed 

with files open. 

SFC 252 RECORD IS LOCKED-OUT — Another 
process is accessing the requested record. 

$FD 253 NON-SHARABLE FILE BUSY — Another 

process is accessing the requested file. 
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Appendix B/Display System 

Functions 



Color Computer OS-9 lets you use the video display in alpha- 
numeric, semigraphic, and graphic modes. There are many 
built-in functions to control the display. These functions are 
activated by various ASCII control characters. The three 
modes are therefore available for use by software written in 
any language using standard output statements (such as 
PRINT in BASIC). The Color Computer BASIC09 language 
has a Graphics Interface Module that can automatically gener- 
ate these codes using BASIC09 RUN statements. 

The display system has two display modes: Alphanumeric 
(" Alpha") mode and Graphics mode. The Alphanumeric 
mode also includes b 'semigraphic 1 ' box-graphics. The Color 
Computer's display system uses a separate memory area for 
each display mode so operations on the Alpha display do not 
affect the Graphics display, and vice-versa. Either display can 
be selected under software control. (Sec the Color Computer 
Manuals for more detailed information.) 

Eight-bit characters sent to the display system arc interpreted 
according to their numerical value, as shown in this chart: 



Character Range (Hex) 


Mode/Used For 




00 - 0E 


Alpha Mode — 
screen control. 


Cursor and 


OF - IB 


Graphics Mode — 
screen control. 


- Drawing and 


1C - 20 


Not used. 




20 - 5F 


Alpha Mode — 
characters. 


Upper case 


60 - 7F 


Alpha Mode — 
characters. 


Lower case 


80 - FF 


Alpha Mode — 
patterns. 


Semigraphic 



The graphics and alphanumeric functions are handled by the 
OS-9 device driver module called CCIO. 
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Alpha Mode Display 



This is the standard operational mode. It's used to display 
alphanumeric characters and semigraphic box graphics, and it 
simulates the operation of a typical computer terminal with 
functions for scrolling, cursor positioning, clear screen, line 
delete, and more. 

Bach 8 -bit character is assumed to be an ASCII character. It 
is displayed if its high order bit (sign bit) is cleared. Bower 
case letters are displayed in reverse video. If the high order 
bit of the character is set, it's assumed to be a ^Semigraphic 
6^ graphics box. See the Color Computer manuals for an 
explanation of semigraphics functions. 



Alpha Mode Command Codes 



Control 

Code Name/Function 

01 HOME — Return cursor to upper left hand corner 
of screen. 

02 CURSOR XY — Move cursor to character X or 
line Y. The binary values minus 32 of the two 
characters following the control eharacter are 
used as the X and Y coordinates. For example, to 
position the cursor at character 5 of line 10, you 
must give X-37 and Y = 42. 

03 ERASE LINE — Erases all characters on the cur- 
sor line. 

06 CURSOR RIGHT — Move cursor right one char- 

acter position. 

08 CURSOR LEFT - Move cursor left one charac- 
ter position. 

09 CURSOR UP — Move cursor up one line. 

10 CURSOR DOWN — (Linefeed) move cursor 
down one line. 
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12 CLEAR SCREEN — Erase entire screen and 
home cursor. 

13 RETURN — Return cursor to leftmost character 
of line. 

14 DISPLAY ALPHA — Switch screen from 
graphic mode to alpha numeric mode. 



Graphics Mode Display 



Graphics mode is used to display high-resolution 2- or 4-color 
graphics. It includes commands to set color, plot and erase 
individual points, draw and erase lines, position the graphics 
cursor, and draw circles. 



The "display graphics 1 ' command must be executed before 
any other graphics mode command is used. It causes the 
graphics screen to be displayed and sets a current display for- 
mat and color. 

The first time the ^display graphics" command is given, OS- 
9 allocates a 6144 byte display memory. So there must be at 
least that much continuous free memory available. (You can 
use the OS -9 Mfrce command to check free memory.) This 
memory is retained until the "end graphics" command is 
given, even if the program that initiated Graphics mode 
finishes. It's important that the "end graphics" command be 
used to give up the display memory when Graphics mode is 
no longer needed. 

Graphics mode supports two basic formats: Two-color, which 
has 256 horizontal by 192 vertical points (G6R mode); and 
Four-color, which has 128-horizontal by 192 vertical points 
(G6C mode). Two color sets are available in either mode. 
Regardless of the resolution of the format selected, all 
Graphics mode commands use a 256 by 192 point coordinate 
system. The X and Y coordinates are always positive num- 
bers. Point 0, is the lower lefthand corner of screen. 
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An invisible Graphics Cursor is used by many commands to 
reduce the amount of output required to generate graphics. 
You can explicitly set this cursor to any point by using the 
"set graphics cursor" command. Also, all other commands 
that include X, Y coordinates (such as "set point") move the 
graphics cursor to the specified position. 



Graphics Mode Selection Codes 



Code Format 

00 256 x 192 two-color graphics 

01 128 X 192 tour-color graphics 



Color Set And Current 
Foreground Color Selection Codes 



Two-Color Format Four-Color Format 

Char Background Foreground Background Foreground 





00 


Black 


Black 


Green 


Green 


Color 


01 


Black 


Green 


(ireen 


Yellow 


Set 1 


02 






(ire en 


Blue 




03 






C ire en 


Red 





04 


Bl; 


iiek 


Bl; 


ack 


Buff 


Buff 


Color 


05 


Bl; 


nek 


Bu 


iff 


Buff 


Cvan 


Set 1 


OCi 

07 










Buff 
Buff 


Magenta 
Orange 




08 










Black 


Blaek 


Color 


09 










Blaek 


Dark Green 


Set 1 


10 
11 










Blaek 
Blaek 


Med. Green 
Light (ireen 




12 










Black 


Black 


Color 


13 










Black 


Green 


Set I 


14 
15 










Blaek 
Blaek 


Red 
Buff 
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Graphics Mode Control Commands 



Control 

Code Name/Function 

15 DISPLAY GRAPHICS — Switches screen to 
graphics mode. This command must be given be- 
fore any other graphics commands are used. The 
first time this command is given, a 6K byte dis- 
play buffer is assigned. If 6K of contiguous mem- 
ory isn't available, an error is returned. Fol- 
low this command by two characters specifying 
the graphics mode and current color/color set, 
respectively. 

16 PRESET SCREEN — Presets entire screen to 
color code passed in next character. 

17 SET COLOR — Selects foreground color (and 
color set) passed in next character, but doesn't 
change graphics mode. 

18 END GRAPHICS — Disables graphics mode, re- 
turns the 6K byte graphics memory area to OS-9 
for other use. and switches to alpha mode. 

19 ERASE GRAPHICS — Erases all points to back- 
ground color and homes graphics cursor to the de- 
sired position. 

20 HOME GRAPHICS CURSOR — Moves 

graphics cursor to coordinates 0, {lower left- 
hand corner). 

21 SET GRAPHICS CURSOR ~- Moves graphics 
cursor to given coordinates X, Y. The binary 
value of two characters that immediately follow 
are used as the X and Y values, respectively. 

22 DRAW LINE — Draws a line of the current fore- 
ground color from the current graphics cursor 
position to the given X, Y coordinates. The bi- 
nary value o{ the two characters that immediately 
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follow are used as the X and Y values, respec- 
tively. The graphics cursor is moved to the end 
point of" the line. 

23 ERASE LINK — Same as tk draw line" except 
that the line is " 'drawn' ' in the current back- 
ground color, thus erasing the line. 

24 SKT POINT — Sets the pixel at point X, Y to the 
current foreground color. The binary values of the 
two characters that immediately follow are used 
as the X and Y values, respectively. The graphics 
cursor is moved to the point set. 

25 ERASE POINT — Same as tL draw point" except 
the point is "drawn" in the current background 
color, thus erasing the point. 

26 DRAW CIRCLE — Draws a circle of the current 
foreground color with its center at the current 
graphics cursor position using a radius R which is 
obtained using the binary value of the next char- 
acter. The graphics cursor position is not affected 
by this command. 



Get Status Commands 



The Color Computer I/O driver includes OS-9 lt get status 1 ' 
commands that return the display status and joystick values, 
respectively. These arc accessible via the BASIC09 Graphics 
Interface Module, or by the assembly language system calls 
listed below: 



Get Display Status: 



Calling Format: Ida #1 (path number) 

klb #SS.DStat (Getstat code $12) 
os9 I$GSTT Call OS-9 
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Passed: nothing 

Returns: X = address of graphics display memory 

Y = graphics cursor address X = MSB 

y = LSB 
A = color code of pixel at cursor address 



Get Joystick Values: 



Calling Format: Ida #1 (path number) 

ldb SSS.Joy (Getstat code $13) 

os9 1$GSTT call OS-9 

Passed: X = for right joystick; 1 for left joystick 

Returns: X = selected joystick x value (0-63) 

Y = selected joystick y value (0-63) 
A - $FF if fire button on; S00 if off 



Display Control Codes Condensed Summary 



1st Byte 2nd Byte 3rd Byte Function 

00 Null 

01 Home alpha cursor 

02 Column + 32 Row + 32 Position alpha cursor 

03 Erase line 



06 




Cursor right 


08 




Cursor left 


09 




Cursor up 


10 




Cursor down 


12 




Clear screen 


13 




Carriage return 


14 




Select alpha mode 


15 


Mode 


Color Code Select graphics mode 
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16 


Color Code 




Preset sereen 


17 


Color Code 




Seleet eolor 


18 






Quit graphics mode 


19 






Krase screen 


20 






Home graphics cursor 


21 


X Coord 


Y Coord 


Move graphics cursor 


22 


X Coord 


Y Coord 


Draw line to X/Y 


23 


X Coord 


Y Coord 


Erase line to X/Y 


24 


X Coord 


Y Coord 


Set point at X/Y 


25 


X Coord 


Y Coord 


Clear point at X/Y 


26 


Radius 




Draw circle 
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Appendix C/Keyboard Codes 



Key Definitions With Hexadecimal Values 



NORM 


SHFT 


CTRL 


NORM 


SHFT 


CTRL 


NORM 


SHFT 


CTRL 


30 


30 






(a 


40 




60 


NUL 00 


P 50 


p 70 


DLE 10 


1 31 


! 21 


| 


7C 


A 


41 


a 


61 


SOH 01 


51 


q 71 


DC1 11 


2 32 


" 22 




00 


B 


42 


b 


62 


SI X 02 


R 52 


r 72 


DC2 12 


3 33 


# 23 


- 


7E 


C 


43 


c 


63 


ETX 03 


S 53 


s 73 


DC3 13 


4 34 


$ 24 




00 


D 


44 


d 


64 


EOT 04 


T 54 


t 74 


DC4 14 


5 35 


% 25 




00 


E 


45 


e 


65 


HMD 05 


U 55 


u 75 


NAK 15 


6 36 


& 26 




00 


F 


46 


f 


66 


ACK 06 


V 56 


v 76 


SYN 16 


7 37 


' 27 


" 


5E 


G 


47 


g 


67 


BEL 07 


W57 


w 77 


ETB 17 


8 38 


( 28 


i 


5B 


H 


48 


h 


68 


BSP 08 


X 58 


x 78 


CAN 18 


9 39 


) 29 


] 


5D 


I 


49 


i 


69 


HT 09 


Y 59 


y 79 


EM 19 


: 3A 


* 2A 




00 


J 


4A 


J 


6A 


LF 0A 


Z 5A 


/ 7A 


SUM 1A 


; 3B 


+ 2B 




00 


K 


4B 


k 


6B 


VT 0B 








, 2C 


< 3C 


{ 


7B 


L 


4C 


1 


6C 


FF 0C 








- 2D 


- 3D 




5F 


M 4D 


m 


6D 


DR 0D 








. 2E 


> 3E 




7D 


N 


4E 


n 


6E 


CO 0E 








1 2F 


? 3F 


\ 


5C 


O 


4F 





6F 


CI OF 









Function Keys 



NORM 



SHFT 



CTRL 



BREAK 


05 


03 


IB 


ENTER 


0D 


01) 


OD 


SPACE 


20 


20 


20 


— 


08 


18 


10 


— 


09 


19 


11 


V 


0A 


1A 


12 


A 


OC 


1C 


13 
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Appendix D/Keyboard Control 

Functions 



Key Definitions for Special Functions 
and Characters 



Key 
Combination 

[CLEAR] 

[BREAK) 

[CLEAR) C=J 



(C LEAR) Q 



(CLEAR) O 



(CLEAR ) (#) 



(CLEAR) CD 
(CLEAR) (BREAK) 

w 

(SHIFT] @ 
(SHIFT) (BREAK] 



(clear) co: 



Control Function or Character 

Used a control key (CTRL). 

Same as (CLEAR) t£j. 

Generates an underline (_) character. The 
underline character is displayed as a left 
arrow (-•-). 

Generates a left brace ({) character. The left 
brace character is displayed as a left bracket 
([ ) in reverse video. 

Generates a right brace (}) character. The 
right brace character is displayed as a right 
bracket (]) in reverse video. 

Generates a tilde <~) character. The tilde is 
displayed as a hyphen (-) in reverse video. 

Generates a reverse slash (\) character. 

Generates an end-of-file (LOL). Same as 
(ESC) on a standard terminal. 

Backspace key or CONTROL II. 

Deletes the entire current line. Same as 
CONTROL X. 

Interrupts the video display of a running 
program. It reactivates the shell and then 
runs the program as a background task. 
Same as CONTROL C. 

Upper/lower case shift lock Junction. 
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(CLEAR) (1j 

(CLEAR] CD 

(CLEAFDQD 
(CHABGD 

(£H£B)QD 
(CLEAR) GD 



(CLEAR) GD 

(clmKCB 



Generates a vertical bar (|) character. The 
vertical bar character is displayed as an ex- 
clamation (!) mark in reverse video. 

Generates an up arrow or caret (') charac- 
ter. 

Generates a left bracket (f) character. 

Generates a right bracket (]) character. 

Repeats previous command line. 

Redisplays current command line on the 
video display. 

Stops the program currently being executed. 
Same as BREAK. 

Temporarily halts output to the screen dis- 
play. Press any key to resume output. 
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23 
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22 
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12 


File Usage 


25 


Text Files 


25 
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26 
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26 
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27 
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28 


FORMAT 


85 


FREE 


86 


Graphics Mode Control 
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IDENT 


87 
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11 


Keyboard 


5 


Shift Functions 


6 


Control Functions 
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Keyboard Codes 
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KILL 


89 


LINK 


90 


LIST 


90 


LOAD 


91 


Loading Multiple Program 


53 


Loading Program Modules 


51 


LOGIN 


93 


MAKDIR 


95 


MDIR 


96 


Memory Fragmentation 


54 


Memory Management 


45 


Memory Management Functions 


50 


MERGE 


97 


MFREE 


98 


Multiprogramming 


45 


Names 


14 


OS-9BOOT 


55 


OS-9 Error Codes 


121 


OS-9 File System 


11 


Organization 


12 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK 
COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 

STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 



CUSTOMER OBLIGATIONS 



LIMITED WARRANTY 



A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the 
'Equipment"), and any copies of Radio Shack software included with the Equipment or licensed 
separately (the "Software") meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER, 

B CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation 

II* RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of me Radio Shack sales document 
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software Is stored is free from manufacturing 
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAiL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION, The warranty Is void if the Equipment's case or cabinet has been opened, or If the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
Is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK'S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable Items, 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is licensed on an "AS IS" basis, 
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

C. Except as provided herein no employee, agent, franchisee, dealer or other person Is authorized to 
give any warranties of any nature on behalf of RADIO SHACK. 

D. Except as provided herein, RADIO SHACK MAKES HO WARRANTIES, INCLUDING WARRANTIES 
OF MERCHANTABILITY OH FITNESS FOR A PARTICULAR PURPOSE. 

E. Some states do not allow limitations on how long an implied warranty lasts, so the above 
limitation(s) may not apply to CUSTOMER. 

HI. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
"EQUIPMENT" OR "SOFTWARE" SOLO. LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATiON OF THE "EQUIPMENT" OR "SOFTWARE". IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE, LEASE, UCENSE, USE OR ANTICIPATED USE OF THE "EQUIPMENT" 
OR "SOFTWARE". 

continued 
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NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BV CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR "EQUIPMENT" OR 'SOFTWARE" 
INVOLVED. 

B. RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

D. Some states do not allow the limitation or exclusion of incidental or consequential damages, so the 
above I imitation (s) or exclusions) may not apply to CUSTOMER. 

IV. RADIO SHACK SOFTWARE LICENSE 

RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on on* computer, subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

B. Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software. 

C. CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals If the Software permits this function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer is expressly 
prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or If additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted to make a limited number of additional copies for 
CUSTOMER'S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 

V. APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

6, The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner and/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 

VI. STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER may have other rights which vary from state to state. 
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OS-9 Program Development 



OS-9 Program Development is in three parts; 

I. Text Editor 

II. Assembler 

III. Interaetive Debugger 

You use these tools in developing an OS-9 program. The Text 
Editor lets you create a source program file. The Assembler lets 
you translate the source file to a machine-language file. With the 
Interaetive Debugger you run and test the source program. 



OS-9 Operating System; < I u X/l Mieroware Systems 

Corporation and Motorola Incorporated. 

All Rights Reserved. 

Licensed lo land) Oorpoialion 

OS- 1 ) Program Development: 

< [ l )H3 Tandy Corporation 

and Mieroware Systems Corporation. 

All Rights Reserved. 

I 'NIX is a trademark o( Bell Laboratories. 

TRS-HO is a registered trademark of Tandy Coiporatioii. 

Reproduction or use, without express written permission from 
Tandy Corporation or Mieroware Systems Corporation of any 
portion of this manual is prohibited. While reasonable efforts hu\c 
been taken in the preparation of this manual to assure its accuracy. 
Tandy Corporation and Mieroware S\ stems Corporal ion assumes no 
liability resulting from any errors or omissions in this manual, or 
from the use of the information contained herein. 
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OS-9 Macro Text Editor 



1 / Introduction 



Overview 



The OS -9 Macro Text Editor is a powerful but simply learned 
text-preparation system. It is commonly used to prepare text for 
letters and documents or text to be used by other OS-9 programs 
such as the assembler and high-level languages. The following 
features of the editor facilitate and expedite the text-preparation 
task. 

• Compact size 

• Multiple read and write files open simultaneously 

• All OS-9 commands usable inside the text editor 

• Adjustable workspace size 

• Repeatable command sequences 

• Edit macros 

• Multiple text buffers 

• Powerful commands 

The Macro Text Editor is an OS-9 executable module in posi- 
tion-independent, reentrant 6809 machine language. It is about 
5K bytes long and requires at least 2K bytes of free RAM to run. 
You may use the editor on any OS-9 system that has disk 
storage. 



Text Buffers 



As you enter text, the editor places it in a temporary storage area 
called a text buffer. Text buffers may be thought of as scratch 
pads used for saving text that you wish to manipulate with 
various edit commands. The Macro Text Editor can use multiple 
text buffers, one at a time. 



The buffer in use is- the "primary buffer/ * and the previous 
primary buffer is the "secondary buffer." This manual refers to 
the primary buffer as the "edit buffer" or "buffer" for short. 
The secondary buffer is important only when you wish to use a 
command that moves text from one buffer to another. 



Edit Pointers 



In the Macro Text Editor an edit pointer identifies your position 
in the buffer. This is similar to holding your place with your 
finger when reading a newspaper. 

Although the screen never shows the edit pointer, commands 
reposition it and display the text to which it points. Bach buffer 
has its own edit pointer, which allows you to move from buffer 
to buffer without losing your place in any of them. 



Entering Commands 



The Macro Text Editor is an interactive editing system. You and 
the editor carry on a two-way conversation that goes through a 
cycle similar to the one below and continues until you type CflD 
to quit editing. 

1 . EDIT shows K: on the screen, asking you to enter a 
command. 

2. You enter (type) a line with one or more commands 
on it. 

3. HDIT carries out the commands. 

4. HDIT shows H: on the screen, asking you to enter a 
command. 

When the screen shows H:, type one or more commands on a 
line and then type dSIIB) (always type (INTER] to end a line). 
Enter each command by typing its name and any parameters 
(values) it needs. 



If you enter more than one command on a line, separate the 
commands with a space. If a space is the first character on a line, 
the editor considers the space an insert command and not a 
separator. 

Correct a typing error by backspacing or by deleting the entire 
line. You cannot correct a line after typing C FNTER ). 

A description of all control characters is in the OS-9 Commands. 
Listed below are some o\ them. 

[ CLEAR ] (Tl 

repeats the previous input line. 



( CLEAR XC) 

interrupts the editor and returns to command entr\ mode. 

fCLEARirPl 

displays the current input on the next line. 

CCLEARXE) or M 

backspaces, erases the previous character. 

ID 

interrupts the editor and returns to command entry mode. 

(C LEAR XW) 

temporarily halts the data output to your terminal so that you can 
read the screen before the data scrolls off. Output resumes when 
you press any other ke\ . 

CCLEARXi). CSHIFTL OR (_— ) 

deletes the line. 

( CLEARI BREAK) 

interrupts the editor and returns to command entry mode. 



Command Parameters 



With many commands you specify a value that represents a 
parameter, for example, the number of times to repeat a com- 
mand or a phrase you wish to find. The two types of edit 
parameters are "numeric" and "string." 



Numeric Parameters 



String Parameters 



Numeric parameters specify an amount, such as the number of 
times to repeat a command or the number of lines that a com- 
mand is to affect. If you do not specify a numeric parameter, the 
editor assumes you intend the default value of one. Specify all 
other numeric parameters in one of the following ways. 

1 . Hnter a positive decimal integer from to 63,333. 
Examples: 


10 

5250 

65532 

31 

2. Hnter an asterisk ( :|; ) as a shorthand for 65,535. This 
is the editor's notation for infinity. The asterisk is 
used to specify all remaining lines, all characters, or 
repeat forever. 

3. Use a numeric variable. (See Hdil Macros, p. 30.) 



String parameters specify a single character, group of charac- 
ters, word, or phrase. Specify string parameters in either of the 
following ways. 

1. tmclose the group of characters with delimiters — 
two matching characters. You may use any charac- 
ters, but they must match. If one string immediately 
follows another, separate the two with a single 
delimiter that matches the others. Examples: 



"string of characters" 

/STRING/ 

: my name is Larry : 

"first string" second string" 

/string 1/ string 2/ 

Use a string variable. (See Edit Macros, p. 30.) 



Syntax Notation 



Syntax descriptions indicate what to enter and the order in which 
to do it. The command name is first; type this exactly as given. 
Following the command name are the parameters the command 
expects; enter each as it is described in the section on 
parameters. 

The syntax descriptions for each command use the following 
notations: 

// — numeric parameter 
str = string parameter 
CSPACEBAR] - space character 

text — one or more characters terminated by 
typing (ENTER) 

Below are examples of command syntaxes, how the command 
is used, and parameter requirements. 



Syntax 


Usage 


Parameter Reqi 


m 


(CLEARX7) 


None 


Vn 


V 5 


1 numeric 


Ui 


L* 


1 numeric 


Snstr 


S kt my string" 


1 numeric and 1 




S4/hcIlo/ 


string 




S*/search string, 




Ctistrstr 


C* b this"that" 


I numeric and 2 




C3:this string: 


strings 




that string: 






C4/strirm// 





Getting Started 



Start OS-9. When the screen shows OS-9, you are ready to enter 
the editor. To do so, type: 



EDIT (ENTER) 

When the screen shows E: r enter a command. The first com- 
mand to learn is how to quit (exit) the editor. Type QD followed 

by (mm. 

The Q command terminates the editor and returns you to the 
OS-9 Shell, which responds with the OS-9: prompt. Learn a 
little about the other commands. Skim the first three sections on 
commands ("Displaying Text," "Manipulating the Edit Point- 
er, 11 "Inserting and Deleting Lines''). 

Now enter the editor again and work through Sample Session 1 . 
After you have mastered the first three sections of commands, 
move on to the more advanced commands and the other Sample 
Sessions. 

If you work with text files, enter the editor with an initial input 
and/or output file. Although you may open additional files after 
entering the editor, several commands treat the initial files as 
special cases (it is assumed that these files are the main working 
files); therefore, it may be advisable to specify your working 
files when you start the editor. 

Below is a list of ways in which the editor may be started, 
including the effect of each. A file that already exists is referred 
to as oldfile. A file to be created is referred to as newfile. 

EDIT OS-9 loads the editor and starts it. 

There is no initial read or write file. 
Perform text file operations by opening 
files after the editor is started. 

EDIT newfile OS-9 loads the editor and starts it. The 

editor creates a file called newfile, the 
initial write file. There is no initial read 
file; however, files may be read if they 
are opened after the editor is started. 



EDIT oldfile 



OS-9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates a file called SCRATCH; this is 
the initial write file. When the edit ses- 
sion is complete, oldfile is deleted, and 
SCRATCH is given the name oldfile. 
This gives the appearance of oldfile 
being updated. 

Note: The two OS-9 utilities DEL and 
RENAME must be present on your sys- 
tem if you wish to start the editor in this 
manner. 



EDIT oldfile newjtle 



OS 9 loads the editor and starts it. The 
initial read file is oldfile. The editor 
creates newfile, the initial write file. 

The terms oldfile, newfile, and file 
refer to any properly constructed OS-9 
pathlist. 



2 / Edit Commands 



Displaying Text 



lists (displays) the next // lines, starting at the current position of 
the edit pointer. The position of the edit pointer does not 
change. Examples: 

L C ENTER] 

displays the current line. 

If the edit pointer is not at the beginning oi the line, only that 
part of the line from the edit pointer to the end of the line is 
displayed. 



L3 [ENT ER] 

displays the current line and the next two lines. 



L* CENTER) 

displays all text from the current position of the edit pointer to 
the end of the buffer. 

The L command displays text regardless of which verify mode is 
in effect. 



X/i 

Displays n lines that precede the edit pointer. The position of the 
edit pointer does not change. Examples: 

X [ENTER) 

displays any text on the current line that precedes the edit 
pointer. If the edit pointer is at the beginning of the line, nothing 
is displayed. 
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)<3 dsnH) 

displays the two preceding lines and any text on the current line 
that precedes the edit pointer. 

The X command displays text regardless of which verify mode 
is in effect. 



Manipulating the Edit Pointer 



moves the edit pointer to the beginning (first character) of the 
text buffer. The screen shows the up arrow when you hold down 
(JtEAFf) and type (Y). Example: 

(CLEAffiCDdBTlH) 

moves the edit pointer to the beginning of the buffer. 

/ 

moves the edit pointer to the end (last character) of the buffer. 
Example: 



/ (ENTER) 

moves the edit pointer past the end of the buffer. 

dsna) 

moves the edit pointer to the beginning of the next line and 
displays it. 

This command is useful forgoing through text one line at a time. 
For example, you may want to look at each line, correct any 
mistakes, and then move to the next line. 



+ n 

Moves the edit pointer either to the end of the line or forward n 
lines and displays the line. Entering a value of zero moves the 
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edit pointer to the end of the current line. Example: 



+ (ENTER) 

Entering a value other than zero moves the edit pointer forward 
n lines and displays the line. Examples; 



+ (ENIER) 

moves the edit pointer to the next line and displays the line. This 
command performs the same function as (ENTER) 

+ 10 (JNTER) 

moves the edit pointer forward 10 lines and displays the line. 



+ * CENTER) 

moves the edit pointer to the end of the buffer. 



moves the edit pointer either to the beginning of the line or back 
(toward the top) n lines. Examples: 

-0 (INTER) 

moves the edit pointer to the beginning of the line and displays 
the line. 

Entering a value other than zero moves the edit pointer back n 
lines. Examples: 

- dBUB 

moves the edit pointer back one line and displays it. 



-5 (ENTER) 

moves the edit pointer back five lines and displays the line. 
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* (INTER) 

moves the edit pointer to the beginning (top) of the buffer and 
displays the first line. 

>n 

Moves the edit pointer to the right n characters. This command 
is used primarily to move the edit pointer to some position in the 
line other than the first character. Examples: 

> (BBSS) 

moves the edit pointer to the right one character. 

>25 (ENTER) 
moves the edit pointer to the right 25 characters. 

>* dHHB) 

moves the edit pointer to the end of the buffer. 

<n 

moves the edit pointer to the left n characters. This command is 
used primarily to move the edit pointer to some position in a line 
other than the first character. Examples: 

< (INTER) 

moves the edit pointer to the left one character. 

< i o dsnE) 

moves the edit pointer to the left 10 eharaeters. 



<* (ENTER) 

moves the edit pointer to the beginning of the buffer. 
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Inserting and Deleting Lines 



(SPACEBAR) text 

inserts lines you enter from the keyboard. The lines are inserted 
before the current position of the edit pointer. The position of 
the edit pointer does not change. The first character you type is a 
space. Examples: 



(SPACE BAR)! NSERT THIS LINE CENTER ) 
inserts the line. 



(SPACEBARS I NE ONE (ENTER ) 
(SPACEBAR) !. I NE TWO (ENTER) 



(SPAClBAffiLINE THREE SNUB) 
inserts three lines. 

In str 

Inserts a line of n copies of the string. The line is inserted before 
the position of the edit pointer, and the position of the edit 
pointer does not change. Example: 

140/*/ (ENTER) 

inserts a line containing 80 asterisks. 

This is useful when outlining a portion of text. You can also use 
the w i" command to insert a line containing a single copy of the 
string. This is important when you want to use a macro to insert 
lines, since the (SPACEBAR) is not used within a macro. Example: 



I "LINE TO INSERT" (ENTER) 
inserts the line. 

D/i 

deletes (removes) n lines from the edit buffer, starting with the 
current line. This command displays the lines to be deleted. 
Examples: 
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D (ENTERJ 

deletes the current line — regardless of the position of the edit 
pointer — and displays it. 



D4 CENTER) 

deletes the current line and the next three lines. 

d* dHlffi) 

deletes everything from the current line to the end of the buffer. 

K« 

kills (deletes) n characters, starting at the current position of the 
edit pointer. This command displays all deleted characters. 
Examples: 



K CENTER) 

deletes the character at the current position of the edit pointer. 

KVi INTER) 

deletes the character at the current position of the edit pointer 
and the next three characters. 



k* dHUB) 

deletes everything from the current position of the edit pointer to 
the end of the buffer. 



En str 

extends n lines by adding a string to the end of each line. This is 
useful, for example, for adding comments to assembly language 
statements. This command extends the line, displays it, and 
then moves the edit pointer past it. Examples: 



E / t h i s is a comment/ (ENTER) 

adds the string "this is a comment'" to the end of the current line 
and moves the edit pointer to the next line. 
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E3/XX CENTER) 

adds the string XX to the end of the current line and the next two 
lines and moves the edit pointer past these lines. 

U 

unextends (deletes) the remainder of a line from the current 
position of the edit pointer. This command is commonly used to 
remove extensions, such as comments, from a line. Example: 

u cenur) 

deletes all the characters from the current position of the edit 
pointer up to the end of the current line. 

For some practice in using the commands that display text, 
manipulate the edit pointer, and insert and delete lines, turn to 
Sample Session 1 . 



Searching and Substituting 



S« string 

searches for the next n occurrences of the string. When it finds 
the occurrence, it displays the line, and moves the edit pointer 
past it. If it does not find the string, the edit pointer does not 
move. Examples: 

S/fny s t r i n * / (HDlR) 

searches for the next occurrence of "my string." 



S3 " s t r un tf out " (ENTER) 
searches for the next three occurrences of "strung out." 



S*/seek and find/ INTER) 

searches lor all occurrences of "seek and find" that are between 
the edit pointer and the end of the text. 
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C/f string! string! 

changes the next n occurrences of string / to string!. When it 
finds string/, it moves the edit pointer past it and changes 
string/ to string!: then it displays the updated line. If it does not 
find string/, the edit pointer does not move. Examples; 



C/this/that/ (ENTER) 
changes the next occurrence of "this 11 to ^ 'that . 



C2/ in/out/ (ENTER) 
changes the next two occurrences of "in" to "out," 

C * ! seek and f i n d ! s o u 3 h t and f o u n d ! 



(MUR) 

changes all occurrences of "seek and find" to "sought and 
found" that arc between the edit pointer and the end of text. 

An 

sets the SEARCH/CHANGE anchor to Column n. To find a 
string that begins in Column 1 (such as an assembly language 
label) but that you don't want to find if it begins in any other 
column, set the anchor to Column 1 before using the search 
command to find it. Examples: 



A (E NTER) 

finds a string only if it begins in Column 1 . 



A50 dSUR] 

finds a string only if it begins in Column 50. 

To return to the normal mode of searching, set the anchor to 
zero. You can now find a string regardless oi' the column in 
which it begins. Example: 
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A0 [ENTER] 

If you use the A command to set the anchor, this setting remains 
in effect only for the current command line. Alter KDIT ex- 
ecutes the command, the anchor automatically returns to its 
normal value of zero. 

For some practice in using the commands that search and 
substitute, turn to Sample Session 2. 



Miscellaneous Commands 



Tn 

tabs (moves) the edit pointer to Column // of the current line. If/? 
exceeds the line length, this command extends the line with 
spaces. Examples: 



T (ENTER) 
moves the edit pointer to Column 1 oi* the current line. 



T5 (ENTER] 

moves the edit pointer to Column 5 of the current line. 

.SHELL command line 

lets you use any OS-9 command from within the editor. The 
remainder of the command line following .SHKLL passes to the 
OS-9 Shell for execution. Examples: 



♦ SHELL DIR /Di GENTER) 
calls the OS-9 Shell to print the directory Dl. 



♦ SHELL BASIC0S (fNUB) 
starts BASIC09. 



♦ SHELL EDIT old file newfile (ENTER] 
starts another copy of the editor. 
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Ma/ 

adjusts the amount of memory available for buffers and macros. 
If the workspace is lull and the editor does not allow you to enter 
more text, increase the workspace si/e. If you will use little of 
the available workspace, decrease the workspace si/e so that 
other OS- 1 ) programs may use the memory that you free. 
Examples: 

M5000 CENTER) 

sets the workspace size to 5,000 bytes. 

M10000 (ENTER) 

sets the workspace size to 10,000 bytes. 

Before typing CD to quit editing, you may want to increase the 
workspace. This decreases the amount of time needed to copy 
the input file to the output file, since the editor is then able to 
read and write more of the file at one time. Memory is allocated 
in 256-hvte pages; therefore, for the M command to have any 
effect, the desired workspace size must differ from the current 
size by at least 256 bytes. The M command does not let you 
return any part of the workspace that is being used tor buffers or 
macros. 

.SIZE 

displays the size of the workspace and the amount that has been 
used. Example: 

♦ SIZE 

521 15328 

521 is the amount of workspace used for buffers and macros. 
15328 is the amount of memory available in the workspace. 

Q 

ends editing and returns to the OS-9 Shell. 

If you specified files when you started the editor, the text in 
Buffer 1 is written out to the initial write file (the one you 
specified when you started EDIT). The remainder of the initial 
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input file (the one you specified when you started EDIT) is then 
copied to the initial write file. After the text is copied, the editor 
terminates and control returns to the OS-9 Shell. 

\mode 

turns the verily mode on or off. When you start the editor, the 
verify mode is on; therefore, the editor displays the results of all 
commands for which results can be displayed. If you do not 
want to see the results of commands, turn off the verify mode by 
specifying (zero) for mode. Hxamplc: 

U0 (ENTER] 

turns off the verify mode. 

To return to the verify mode, specify any nonzero value for 
mode. Examples: 



turns on the verify mode. 



V 1 3 (ENTER ) 

turns on the verify mode. 

If the verify mode is on and you switch to a macro, it remains 
on. If you turn off the verify mode while in the macro, it is 
automatically restored when you return to the editor. 



Manipulating Multiple Buffers 



.MR 

displays the directory of the editor's buffers and macros, which 
is similar to the one below: 

BUFFERS: 

$ (secondary buffer) 
* 1 (primary buffer) 
50 ( anothe r buffer) 
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MACROS: 



MYMACRO 

LIST 

COPY 



makes buffer // the primary buffer. When you switeh from one 
buffer to another, the old one becomes the secondary buffer and 
the new one becomes the primary buffer. Example: 



B5 SNUB 

makes Buffer 5 the primary buffer; if Buffer 5 docs not exist, it 
is created. 



puts (moves) /; lines into the secondary buffer. This command 
removes the lines from the primary buffer, starting at the posi- 
tion of the edit pointer and inserts them into the secondary buffer 
before the current position of the edit pointer. It displays the text 
that is moved. Examples: 

p (EH1H) 

moves one line to the secondary buffer. 

P5 CENTER) 
moves five lines to the secondary buffer. 



P# (MTER) 

moves to the secondary buffer all lines that arc between the 
current position of the edit pointer and the end of text. 

G« 

gets (moves) n lines from the secondary buffer. This command 
takes the lines from the top of the secondary buffer and inserts 
them into the primary buffer before the current position of the 
edit pointer. It displays the lines that are moved. When used 
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with the P command, the G command moves text from one 
place to another. Examples: 

G CENTER) 

gets one line from the secondary buffer. 



G5 (MM) 

gets five lines from the secondary buffer. 

G* (INTER) 

gets all lines from the secondary buffer. 

For some practice in using miscellaneous commands and the 
commands that manipulate multiple buffers, turn to Sample 
Session 3. 



Text File Operations 



This section of the manual describes the group of commands 
related to reading and writing OS-9 text files. 

.NEW 

gets new text. This command is used when editing a file that is 
too large to fit into the editor's workspace at one time. .NEW 
writes out all lines that precede the current line and then the 
editor tries to read in an equal amount of new text that is 
appended to the end of the buffer. 

The NEW command always writes text to the initial output file 
(the one created when you started the editor) and always reads 
text from the initial input file (the one specified when you 
started the editor). 

If you have finished editing the text currently in the buffer, you 
may tb flush' ' out this text and fill the buffer with new text by 
moving the edit pointer to the bottom of the buffer and then 
using the .NEW command. Example: 



/ *NEW (ENTER) 
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If you wish lo retain part of the text that is already in the buffer, 
move the edit pointer to the first line you wish to retain and then 
type CD NEW. This "flushes" out all lines that precede the edit 
pointer. It then tries to read in new text that is the same size as 
the portion Hushed out. 

.READ str 

prepares an OS-9 text file tor reading; str specifies the pathlist. 
Example: 

♦ READ "myfile" (ISlIB) 
closes the current input file and opens "myfile" for reading. 
You may specify an empty pathlist. Example; 



♦ READ " " (ENTER) 

closes the current input file and restores the initial input file (the 
one you specified when you started the editor) for reading. 

An open file remains attached to the primary buffer until you 
close the file. You may have more than one input file open at 
any time by using the .READ command to open them in differ- 
ent buffers. 

To read these files, switch to the proper buffer, and then use the 
R command to read from that buffer's input file. To close a file, 
you must be in the same buffer in which the file was opened. 

.WRITE str 

opens a new file for writing. The string specifies the pathlist for 
the file you wish to create. Example: 



♦ WRITE "newfi le" (ENTER) 
closes the current write file and creates one called "newfile.' 
You may specify an empty pathlist. Example: 



♦ WRITE " " (ENUR) 

closes the current write file and restores the initial write file (the 
one you specified when you started the editor). 
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A new write file is attached to the primary buffer and remains 
attached until you close the file. You may have more than one 
write file open by using the .WRITE command to open them in 
different buffers. To write these files, switch to the proper 
buffer and then write that buffer's file. To close a file, you must 
be in the same buffer in which the file was opened. 

R/i 

reads (gets) n lines of text from the buffer's input file. It displays 
the lines and inserts them before the current position of the edit 
pointer. Examples: 



R CENTER! 

reads one line from the input file. 



R 10. CENTER) 
reads 10 lines from the input file. 

R* CENTER] 

reads the remaining lines from the input file. 

If a file contains no more text, the screen shows the *END OF 
FILE* message. 

Wn 

writes n lines to the output file, starting with the current line. It 
displays ail lines that are deleted from the buffer. Examples: 



1*1 CENTER) 

writes the current line to the output file. 



W5 CENTTR) 
writes the current line and the next four lines to the output file. 



W* (ENTER) 

writes all lines from the current line to the end of the buffer to the 
output file. 
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For some practice in using the commands that read and write 
OS- c ) text files, turn to Sample Session 4. 



Conditionals and Command Series Repetition 



When a command cannot be executed, the editor sets an internal 
Hag, and the screen shows FAIL. For example, if you try to read 
from a file that has no more text, the editor sets the fail flag. 
After the fail flag is set, the editor will not execute any more 
commands until one of the following conditions is met: 

1 . The end of a command line is reached if it was typed 
in from the keyboard. 

2. The end of the current loop is reached. Any loops 
that are more deeply nested will be skipped. (See 
the repeat command.) 

3. A colon (:) command is encountered. Since loops 
that are nested deeper than the current level are 
skipped, any occurrences of : that are in a more 
deeply nested loop will also be skipped. 

Below arc commands that set the fail flag and the condition on 
which it is set: 



< 



Trying to move the edit pointer beyond the begin- 
ning o( the edit buffer. 



> Trying to move the edit pointer beyond the + end 

of the buffer. 

S,C Not finding a string that was searched for. 

G No text left in the secondary buffer. 

R No text left in the read file. 

P,W No text left in the primary buffer. 

If you specify an asterisk for the repeat count on these com- 
mands, the fail flag is not set. This is because an asterisk usually 
means continue until there is nothing more to do, and the 
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commands succeed in doing just that. In addition to these 
commands that set the fail flag as a side effect, the following 
commands explicitly set the fail flag if some condition is not 
true . 



.EOF 

tests for end of file. This succeeds if there is no more text to read 
from the file; otherwise, it sets the fail flag. 

.NEOF 

tests for not end of file. This succeeds if there is text to read from 
the file; otherwise, it sets the fail flag. 

.EOB 

tests for end of buffer. This succeeds if the edit pointer is at the 
end of the buffer; otherwise, it sets the fail flag. 

.NEOB 

tests for not end of buffer. This succeeds if the edit pointer is not 
at the end of the buffer; otherwise it sets the fail Hag. 

.EOL 

tests for end of line. This succeeds if the edit pointer is at the end 
of the line; otherwise, it sets the fail flag. 

.NEOL 

tests for not end of line. This succeeds if the edit pointer is not at 
the end of the line; otherwise, it sets the fail ilag. 

.ZERO n 

tests for zero value. This succeeds if/? equals zero; otherwise, it 
sets the fail flag. 
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.STAR n 

tests for star (asterisk). This succeeds tf'n equals 65,535 r^*^); 
otherwise, it sets the fail flag. 

.STR str 

tests tor string match. This succeeds if the characters at the 
current position of the edit pointer match the string; otherwise, it 
sets the fail flag. 

.NSTR str 

tests for string mismatch. This succeeds if the characters at the 
current position of the edit pointer do not match the string; 
otherwise, it sets the fail Hag. 

.S 

exits and succeeds. This is an unconditional exit from the 
innermost loop or macro. The fail Hag clears after the exit. 



exits and fails. This is an unconditional exit from the innermost 
loop or macro. The fail flag sets after the exit. 

[commands I n 

repeats the commands n times. Left and right brackets form a 
loop that repeats the enclosed commands n times (the loop must 
be repeated at least once). If the loop is entered from the 
keyboard, it must all be on one line. If it is part of a macro, 
however, it may span several command lines. Examples: 



repeats the L command iivc times. 

Note: This is not exactly the same as L5, which executes the L 
command only once and has 5 as its parameter. 
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[ + ]* CENTER) 

displays lines starting with the next line up to the end of the 
buffer and moves the edit pointer to the end of the buffer. 

This command repeats the + command until the end of the 
buffer is reached. Then when the command tries to move the 
edit pointer past the end of the buffer, the fail flag is set; this 
terminates the loop and clears the fail (lag. 

Whenever the end of the loop is reached and the fail Hag is set, 
the current loop is terminated and the fail flag is cleared. 

: commands 

decides whether or not to execute the commands that follow it, 
depending on the state of the fail flag. Below are the actions 
taken as a result of the colon (:) being executed and the state of 
the fail flag. 

FAIL FLAG CLEAR Skips all commands that fol- 

low the colon {:) up to the end 
of the current loop or macro. 

FAIL FLAG SET Clears the fail flag and ex- 

ecutes the commands that fol- 
low the colon (:). 

Below is a command line that deletes all lines that do not begin 
with the letter A. 

(CHAffiCD [ .NEOB L ♦STR"A" + : 
D ] ] * 

The CD moves the edit pointer to the beginning of the buffer. 
The outer loop tests for the end of the buffer and terminates the 
loop when it is reached. 

The inner loop tests for// A at the beginning of the line. If there 
is one, the -+ command is executed; otherwise, the D command 
is executed. 

Below is a command that searches the current line for "find it." 
If the command finds "find it/ 1 the screen shows the line. 
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Edit Macros 



Otherwise, the command line fails and the screen shows 
* FAIL *. 

C + E0L V0 -0 U .F : ♦ STR" find it" 
- ♦ S :[>]]* 

.EOF VO -0 V .F tests to determine if the edit pointer is at the 
end of the line. If it is, the verify mode is turned off to prevent 
the -0 from displaying the line. Then it is turned back on, and the 
.F ends the loop. 

If the edit pointer is not at the end of the line, the .STR command 
searches for 'Mind if 1 at the current position of the edit pointer. 
If it is at the end of the line, the -0 .S commands are executed. 
This moves the edit pointer back to the beginning of the line, 
displays the line, and terminates the loop. Otherwise, the > 
command moves the edit pointer to the next position in the line. 

The brackets prevent the command from failing and terminating 
the main loop if the end of the buffer is reached. 



"Fdit macros" are commands you create to perform a special- 
ized or complex task. For example, you can replace a frequently 
used series of commands with a single macro. First, save the 
series in a macro. Then each time you need it, type a period 
followed by the macro's name and parameters. The editor 
responds as if you had typed the scries of commands. 

Macros consist of two main parts — the header and the body. 
The header gives the macro a name and describes the type and 
order of its parameters. The body is made up of any number of 
ordinary commands (except for (SPMB3B and dNTER), any 
command may be used in a macro). Note: Macros cannot create 
new macros. 

To create a macro, first define it with the .MAC command. 
Then enter the header and body just as you would enter tett into 
an edit buffer. When you are satisfied with the macro, close its 
definition by typing QD. This returns you to the normal edit 
mode. 
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Macro Headers 



A macro header must be the first line in each macro. It is made 
up of a name, which may be followed by a ' 'variable list" that 
describes the macro's parameters if there are any. The name 
consists of any number of consecutive letters and underline 
characters. Examples: 

MACRO 

trim_spaces 

LIST 

EXTRA_LONG_MACRO_NAME 

Although you may make a macro name any length, it is better to 
keep it short because you must spell it the same each time you 
use it. You may use upper- and lower-case letters or a mixture. 



Parameter Passing 



Like other commands, macros may be given parameters so that 
they are able to work with different strings and numbers of 
things. Macros are unable to use parameters directly; instead, 
the parameters are passed on to the commands that make up the 
macro. 

To pass the macro's parameters to these commands, use the 
variable list in the macro header to tell each command which of 
the macro's parameters to use. Each variable in the variable list 
represents the value of the macro parameter in its corresponding 
position. Use the corresponding variable wherever the param- 
eter's value is needed. 

The two types of variables are numeric and string. A numeric 
variable is a variable name preceded by the # character. A 
string variable is a variable name preceded by a $ character. 
Variable names, like macro names, are composed of any num- 
ber of consecutive letters and underline characters. Examples of 
numeric variables: 

#N 

#ABC 

#LONCj_NUMBER_VARIABLF 
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Examples of string variables: 

$A 
SB 

$STR 
$STR_A 

$lower_case_variable_name 

The function of the edit macro below is the same as that of the S 
command — to search for the next n occurrences of a string. The 
first line of the macro is the macro header; it declares the 
macro's name to be SRCH. It also specifies that the macro needs 
one numeric parameter (#N) and one string parameter ($STR). 
The entire body of the macro is the second line. Here both of the 
macro's parameters are passed to the S command, which does 
the actual searching. 

SRCH #N $STR 
S #N $STR 

Below is an example of how to execute this macro: 

.SRCH 15 "string" 

In the next example the order of the parameter is reversed. 
Therefore, when executing the macro, use the reverse order. 
Below is the macro definition: 

SRCH $STR #N 
S #N $STR 

Specify the parameters for the "S" command in the proper 
order since it is only the "SRCH' 1 macro that is changed. Below 
is an example of how to execute this macro. The order of the 
parameters directly corresponds to the order of the variables in 
the variable list. 

.SRCH "string" 15 

! text 

places comments inside a macro. Ignore the remainder of the 
line following the ! command. This allows you to include, as 
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part of a macro, a short description of what it does in case you 
forget or in case someone else wants to use the macro. 
Examples: 



CD 

L* 



Move the edit pointer to the top of the buffer. 
Display all lines of text. 



In the example above are four comments; two are empty, and 
two describe the commands that precede them. 



.macro name 

executes the macro specified by the name following the period 
(.). Examples: 

.MYMACRO 

.LIST 

.TRIM " " 

.MERGE " FILE_A " FILE B B" 



.MAC str 

creates a new macro or opens the definition of an existing one so 
that it may be edited. To create a new macro, specify an empty 
string. Example: 



♦ MAC // (ENTER) 

creates a new macro and puts you into the macro mode. 

The screen shows M: instead of E: when the editor is in the 
macro mode. To edit a macro that already exists, specify the 
macro's name. Example: 



♦ MAC "MYMACRO" CENTER) 

opens the macro "MYMACRO" for editing. 

When a macro is open, edit it or enter its definition with the 
same comands you use in a text buffer. After you edit the macro, 
type GOD to close its definition and return to the edit mode. The 
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first line o( the macro must begin with a name that has not 
already been used in order to close the definition and return to 
EDIT. 

.SAVE strl str2 

saves macros on an OS -9 file. String I specifies a list of macros 
to be saved; the macro names are separated by spaces. String! 
specifics the pathlist for the file on which the macros are to be 
saved. Examples: 

.SAVE ^MYMACRO '^YEILE'' 

saves the macro ^MYMACRO' 1 on the file ^YEILE.^ 

.SAVE ^MACA MACB MACC 'MFILE 

saves the macros "MACA. 1 * ^MACB/ 1 and ^MACC" on the 
file lt MFILE. ,, 

To save more than one macro on a file, space between their 
names. 

.SEARCH n str 

searches the text file buffer for the specified string. When a 
match is found, it stops and displays that line. The n option 
permits a search for the nth occurrence of a string match. This 
command is the same as S n str. 

.LOAD str 

loads macros from an OS-9 file. As each macro is loaded, EDIT 
verifies that no other macro exists with that name. A duplicate 
name does not load, and EDIT skips to the next macro on the 
file. EDIT displays the names of all macros it loads. Examples: 

♦LOAD "MACROFILE" 

loads the macros in the file called MACROFILE. 



♦ LOAD "MYFILE" [ENTER) 
loads the macros in the file called MY FILE. 
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.DEL str 

deletes the macro specified by the string. Examples: 

.DEL "MYMACRO" INUR) 
deletes the macro called MYMACRO. 



♦ DEL "LIST" (ENTER) 
deletes the macro called LIST. 

.I)IR 

displays the current edit buffer area. All edit buffers and macros 
currently in memory are displayed. 

.CHANGE n strl str2 

changes the occurrence at string I with string!. The n option 
permits n occurrences at string I to be changed with string!. 



ends a macro edit session. It returns you to the normal edit 
mode. 

Example: 

Search_and_Delete #N $STR 

! This example MACRO is used to check the string at the 

beginning of an #N number of lines. 
! If the string matches, it will delete that line from the text 

buffer file. 

! NOTE: The way the editor processes a MACRO causes it to 
see any parameters in the outer loop first. Thus, the #N 
parameter is processed before the STR parameter. 

CD .'Move to start of edit buffer 

[ .'start of outer loop 

.NKOB !test for buffer end 

| ! start of inner loop 

.NSTR $STR !test for not string match 
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+ !go to next line if no match 

: !if flag clear skip next command 

D .'delete line if Hag set 

] !end of inner loop 

]#N lend of outer loop 

! Knd of Macro 

For some practice in using macro commands, turn to Sample 
Session 5. 
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3 / Sample Sessions 



Sample Session 1 

Clear the buffer by deleting its contents. 
You Type: fCLEAR)7D* CE NTER] 
Screen Shows: E : CD 

Insert three lines into the buffer. Begin each line with a space, 
which is the command for inserting text. 

You Type: (SPACEBA R) MY FIRST LINE (INTER) 
[SPACEBARS Y SECOND LINE CpJTERJ 
[SPACEBAR) MY THIRD LINE (ENTEH) 
Screen Shows: E : MY FIRST LINE 
Es MY SECOND LINE 
Es MY THIRD LINE 

Move the edit pointer to the top of the text. The editor always 
considers the first character you type a command. Note: (CLEAR) 
7 always shows CD on the screen. Typing G3 also moves the 
edit pointer to the beginning of a buffer. 

You Type: (£SEE)7 (ENTER) 

Screen Shows: E s CD 

List (display) the first line you inserted into the buffer. 
You Type: L JNTEH) 
Screen Shows: E : L 

MY FIRST LINE 

Display the first two lines you inserted into the buffer. 
You Type: L2 CrNTER) 
Screen Shows: E : L2 

MY FIRST LINE 
MY SECOND LINE 

Move to the next line and display it. 
You Type: CENTER) 
Screen Shows: E : 

MY SECOND LINE 

Move to the next line and display it. 
You Type: CENTER) 
Screen Shows: E : 

MY THIRD LINE 



37 



Display text beginning at the position of the edit pointer. This is 
the function of L. 

You Type: L (INTER) 

Screen Shows: E s L 

MY THIRD LINE 

Insert a line into the buffer. Note: In the next sample you will 
see that the line is inserted before the current position of the edit 
pointer. 

You Type: (SP ACEBAR) I N 5 E R T A LINE CENTER] 
Screen Shows: E: INSERT A LINE 

The following command line eonsists of more than one com- 
mand. (CLEAR)7 CD moves the edit pointer to the top of the text. 
L displays the text, and the asterisk (*) following L indicates 
that text is displayed through to the end of the buffer. 
You Type: "(CLEAR) 7 L» (FNTER) 
Screen Shows: EsQDL* 

MY FIRST LINE 
NY SECOND LINE 
INSERT A LINE 
MY THIRD LINE 

Show the position of the edit pointer. 
You Type: L (ENTER) 
Screen Shows: E : L 

MY FIRST LINE 

Move the edit pointer forward two lines and display the lines. 
You Type: +2 (ENTEff ) 
Screen Shows: E s +2 

INSERT A LINE 

Display all lines from the edit pointer to the end of the buffer. 
You Type: L# (ENTER) 
Screen Shows: E : L* 

INSERT A LINE 
MY THIRD LINE 

Move the edit pointer to the end of the buffer. 
You Type: / (ENTER) 
Screen Shows: E : / 

Show that the edit pointer is at the end of text. It is, since the 
screen shows no lines. 
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You Type: L* CENTER) 
Screen Shows: E : L* 

Insert two more lines. 



You Type: (SPACEBARS I FT H LINE (ENTER) 

(SPACEBARS . AST LINE (ENTER) 
Screen Shows: E: FIFTH LINE 
E: LAST LINE 

Move the edit pointer back one line and display the line. 
You Type: - 2 (ENTER) 
Screen Shows: E s - 2 

FIFTH LINE 

Move the edit pointer back two lines and display the line. 
You Type: -3 dNTER) 
Screen Shows: E : - 3 

MY SECOND LINE 

Move the edit pointer three characters to the right and display 
the remainder of the line. Note: Space between commands. 

You Type: >3 L CENTER) 

Screen Shows: E : > 3 L 

SECOND LINE 

Display the characters that precede the edit pointer on the 
current line. 



You Type: X CENTER) 
Screen Shows: E : X 

MY 

Move the edit pointer to the end of the current line. 
You Type: +0 (ENTER) 
Screen Shows: E : +0 

Show that the edit pointer is at the end of the line. It is, since the 
screen shows no lines. 



You Type: L (ENTER) 
Screen Shows: E : L 

Display the characters that precede the edit pointer on the 
current line. 



You Type: X (ENTER) 
Screen Shows: E : X 

MY SECOND LINE 
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Move the edit pointer back to the beginning of the current line. 
You Type: -0 (ENTER) 
Screen Shows: E : - 

MY SECOND LINE 

Show that the edit pointer is at the beginning of the line. It is, 
since the screen shows no lines. 

You Type: X (ENTER) 

Screen Shows: E : X 

Go to the beginning of the text. 



You Type: (CLEARJ 7 (ENTER) 
Screen Shows: E : CD 

Insert a line oi 14 asterisks. 



You Type: 114"*" (ENTER) 
Screen Shows: E : I 1 4 " * " 

■*■*•##•*****##*## 

Insert an empty line. 



You Type: I " " CENTER) 
Screen Shows: E : I" " 

Move to the top of the text and display all lines in the buffer. 
You Type: (CLEAR) 7L* (ENTER) 
Screen Shows: E : QDL* 

#**■*#•*##***•*■** 

MY FIRST LINE 
MY SECOND LINE 
INSERT A LINE 
MY THIRD LINE 
FIFTH LINE 
LAST LINE 

Move the edit pointer forward two lines. 
You Type: +2 (ENTER) 
Screen Shows: E ; +2 

MY FIRST LINE 

Extend the line with XXX. 



You Type: E " XXX" (ENTER) 
Screen Shows: E:E" XXX" 

MY FIRST LINE XXX 
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Display the current line. Note: The previous E command moved 
the edit pointer to the next line. 

You Type: L (ENTER) 

Screen Shows: E : L 

MY SECOND LINE 

Extend three lines with YYY. 



You Type: E3" CSPACEB AR)¥YY" (ENTER) 

Screen Shows: E : E3 " YYY " 

MY SECOND LINE YYY 
INSERT A LINE YYY 
MY THIRD LINE YYY 

Move back 2 lines. 

You Type: - 2 dNJERD 
Screen Shows: E : - 2 

INSERT A LINE YYY 

Move the edit pointer to the end of the line; move the edit pointer 
back tour characters; display the current line, starting at the edit 
pointer. 

You Type: +0 < 4 L ( ENTER) 

Screen Shows: E : +0 < 4 L 



Truncate the line at the current position of the edit pointer. This 
removes the YYY extension. 



You Type: U (ENTER) 
Screen Shows: E : U 

INSERT A LINE 

Go to the top of the text and display the contents of the buffer. 
You Type: (CLEAR )7L* (ENTER] 
Screen Shows: E sCDL* 

MY FIRST LINE XXX 
MY SECOND LINE YYY 
INSERT A LINE 
MY THIRD L: 
FIFTH LINE 
LAST LINE 
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Delete the current line and the next line. 



You Type: D2 (ENTER ) 
Screen Shows: E s 02 

Move the edit pointer forward two lines. 
You Type: +2 (ENTER) 
Screen Shows: E ; +2 

INSERT A LINE 

Delete this line. 



You Type: D (ENTER) 
Screen Shows: E s D 

INSERT A LINE 

Display the current line. 



You Type: L (ENTER) 

Screen Shows: E: MY THIRD LINE YYY 

Move the edit pointer to the right three charaeters and display 
the text. 



You Type: >3 L (ENTER) 
Screen Shows: E : >3 L 

THIRD LINE YYY 

Kill (delete) the 1 1 characters that constitute THIRD LINE. 
You Type: K 1 1 (ENTER) 
Screen Shows: E : K 1 i 

THIRD LINE 

Go to the beginning of the line and display it. 
You Type: - (ENTER) 

Screen Shows: E s - 

M\/ \/ \/ \/ 
i it) 

Concatenate (combine) two lines. Move the edit pointer to the 
end of the line; delete the character at the end of the line; move 
the edit pointer back to the beginning of the lines. Display the 
line. 

You Type: +0 K -0 (ENTER) 

Screen Shows: E: +0 K -0 

MY YYYFIFTH LINE 
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Separate the two lines by inserting an end-of-line character. 
You Type: >B I// (ENTER) 
Screen Shows: E : >6 I / / 

MY YYY 

Note: The empty line is inserted before the current position of 
the edit pointer. 

You Type: L (ENTER) 

Screen Shows: E : L 

FIFTH LINE 



Sample Session 2 



Clear the buffer by deleting its contents. 



You Type: (CLEARJ7D* (ENTER) 




Screen Shows: E : CDO* 




nsert lines. 




You 




Type: (SPAC 
(SPAf 
(SPAC 


EBARjQNE TWO THREE 1 t 


(ENTER) 


EBAR)0NE (ENTER) 




EBARXSPACEBAR)TWO (ENTER) 




(SPACEBARXSPACEBARXSPACEBAR) 




THREE (ENTER) 




(SPAC 
(SPAC 
(SPAC 
(SPAC 

1 


EBAR)0NE TWO THREE 2*0 


(ENTER) 


EBAR)0NE (ENTER) 




EBAR)(SPACEBAR)TWO (ENTER) 




E B ARXSP AC E BARXSP AC E B AR) 




fHREE (ENTER) 




(SPACEBAR)ONE TWO THREE 3*0 


(ENTER) 


Screen Shows: E: ONE TNO THREE 1 


,0 


E 


ONE 




E 


TWO 




E 


THREE 




E 


ONE TWO THREE 2*0 




E 


ONE 




E 


TWO 




E 


THREE 




E 


ONE TWO THREE 3.0 
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Go to the top of the text and display all lines in the butter. 
You Type: CCTBBPL* tlNTER) 
Screen Shows:0E : ( f)L * 

ONE TWO THREE i .0 
ONE 
TWO 
THREE 
ONE TWO THREE 2*0 
ONE 
TWO 
THREE 
ONE TWO THREE 3,0 

Search for the next occurrence of TWO. The edit pointer moves 
past the letter O in TWO; the entire line is found and displayed. 

You Type: S H T W " IWSO 

Screen Shows: E : S " TWO " 

ONE TWO THREE 1*0 

Show that the edit pointer has moved. 
You Type: L (ENTER) 
Screen Shows: E s L 

THREE 1 ,0 

Search for all occurrences of '"TWO" 1 that are between the edii 
pointer and the end of the buffer. When "TWO" is found, the 
edit pointer moves past it and the line is displayed. 
You Type: ♦ S * / T W / (ENTIR] 

Screen Shows: E:S*/TWO/ 

ONE TWO THREE 1 ,0 

TWO 
ONE TWO THREE 2.0 

TWO 
ONE TWO THREE 3*0 

Go to the top of the buffer and change the first occurrence of 
THRHH to ONH. 

You Type: (CLEARS C/THREE/ONE/ 

Screen Shows: E : (T) C/ THREE/ONE/ 
ONE TWO ONE 1 ,0 
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Show that the edit pointer has moved past the string that was 
e hanged. 

You Type: L ( ENTER) 

Screen Shows: E : L 

1 ,0 

Move the edit pointer to the top of the buffer. Set the anchor to 
Column 2 and then use the search command to find each 
occurrence of TWO that begins in Column 2. All other occur- 
rences are skipped. 

You Type: ( CLEAR] 7 A2 S* / TWO/ (INTER) 
Screen Shows: E:CD A 2 S*/TWO/ 
TWO 
TWO 

Move the edit pointer to the top of the buffer. Set the anchor to 
Column 1, and change each occurrence of ONH that begins in 
that column to XXX. Note: ONt: in Line 1 is not changed, since 
it does not beizin in Column 1 . 

You Type: (CLEAR) 7 A 1 C*/ ONE /)<)<)</ (INTER) 
Screen Shows: E : CD A 1 C * / N E / K X X / 

XXX TWO ONE i ,0 

\ / \ / \ i 

A A A 

XXX TWO THREE 2*0 

A A / \ 

XXX TWO THREE 3*0 

THREE 

XXX TWO THREE 2.0 
\/ \/ \/ 

A A /\ 

TWO 
THREE 
XXX TWO THREE 3,0 

Go to the top of the buffer and displa} the text. 
You Type: CCLEAR)7L* CENTER) 
Screen Shows: E : CIX* 

XXX TWO ONE 1 *0 



TWO 
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Change the remaining ONE to XXX. Note: The anchor is no 
longer set. It is reset to zero after each command is executed. 

You Type: < ♦ C H A N G E / N E / X X X / [ENTER] 

Screen Shows: E : C / N E / X X X / 

XXX TWO XXX 1 t 

Move to the beginning of the current line. 
You Type: - dSUR] 
Screen Shows: E : - 

XXX TWO XXX 1 .0 

Change three occurrences of "XXX" to "ZZZ." 
You Type: ♦ C3/XXX/ZZZ/ dNTER) 
Screen Shows: E : C 3 / X X X / Z Z Z / 

ZZZ TWO XXX 1 ,0 
ZZZ TWO ZZZ 1 ♦ J0 



Sample Session 3 



Clear the buffer by deleting its contents: 
You Type: (0121)7 D* CENTER) 
Screen Shows: E : d)D* 

Oisplay the directory of buffers and macros. The dollar sign ($) 
identifies the secondary buffer as Buffer 0; the asterisk (*) 
identifies the primary buffer as Buffer 1 . No macros are defined. 
This is the initial environment when KDIT is started from OS-9. 

You Type: ♦ D I R (ENTER] 

Screen Shows: E : ♦ D I R 

BUFFERS: 
$ 

* 1 

MACROS: 

Insert some lines into Buffer 1 so that later you can identify it. 

You Type: (SPACE BAR) BUFFER ONE 1*0 (ENTER] 

dPA£HAB)BUFFER ONE 2*0 dNTER) 



(SHEHAffiBUFFER ONE 3*0 dNTER) 
(SPACHSBBUFFER ONE 4 t (ENTER) 
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Screen Shows: E 

E 



BUFFER ONE i ,0 

BUFFER ONE 2*0 

BUFFER ONE 3.0 

BUFFER ONE 4.0 



Display the text in Buffer 1. 




YouTvpe: (CLEAR]7L* (ENTER) 




Screen Shows: E : GDI-* 




BUFFER ONE 


1 .0 


BUFFER ONE 


2.0 


BUFFER ONE 


3,0 


BUFFER ONE 


4.0 



Make Buffer the primary buffer. Buffer 1 becomes the second- 
ary buffer. 

You Type: B0 (ENTER) 

Screen Shows: E : B0 

Display the directory of buffers and macros. Note: The symbols 
identifying the buffers arc now reversed. 

You Type: ♦ D I R CENTER] 

Screen Shows: E : ♦ D I R 

BUFFERS: 

$ 1 
* 

MACROS; 

Insert some lines into Buffer 0. 
You 



Type: (SPAC E BARS UFFER ZERO 1.0 GBTffi] 
(SPACEBAR) BUFFER ZERO 2,0 [ENTER] 
(SPA CEBAffi BUFFER ZERO 3.0 CENTER ] 
(SPACEB ARS UFFER ZERO 4.0 (ENTER) 
Screen Shows: E : BUFFER ZERO 1*0 
E: BUFFER ZERO 2.0 
E: BUFFER ZERO 3.0 
E: BUFFER ZERO 4.0 

Display the text in Buffer 0. 

You Type: (CLEAR) 7 L* (ENTER) 
Screen Shows: E :CT)L* 

BUFFER ZERO 1 .0 
BUFFER ZERO 2.0 
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BUFFER ZERO 3*0 
BUFFER ZERO 4*0 



Switch to Buffer 1. 

You Type: B (ENTER) 
Screen Shows: E : B 

Display the text in Buffer 1. 



You Type: (CLEARpL* (ENTER) 




Screen Shows: E :(TX* 




BUFFER ONE 


1 t 


BUFFER ONE 


2*0 


BUFFER ONE 


3*0 



BUFFER ONE 4,0 

Move the edit pointer to Line 3 in this buffer. 
You Type: + 2 (ENTER) 
Screen Shows: Es+2 

BUFFER ONE 3*0 

Switch to Buffer 0. 

You Type: B0 (HmB) 
Screen Shows: E s B0 

Display the text in Buffer 0. 



You Type: L* (ENTER) 








Screen Shows: E : L* 








BUFFER 


ZERO 


1 ■ 


,0 


BUFFER 


ZERO 


*? 


,0 


BUFFER 


ZERO 


3 


♦ 


BUFFER 


ZERO 


a 


♦ 



Move the edit pointer to Line 2 in this buffer. 
You Type: + (MSE) 
Screen Shows; E s + 

BUFFER ZERO 

Switch to Buffer I . 



You Type: B (ENTM) 
Screen Shows: E ; B 

Display the text in Buffer 1 from the current position of the edit 
pointer. Note: The position of the edit pointer has not changed 
since you switched to Buffer 0. 
You Type: L* (ENTfR) 
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Screen Shows: E : L* 

BUFFER ONE 3*0 
BUFFER ONE a * 

Switch to Buffer 0. 

You Type: B0 (ENTER) 
Screen Shows: E : B0 

Display the text in Buffer from the current position of the edit 
pointer. Note: The position of the edit pointer has not changed 
since you switched to Buffer 1 . 

You Type: L* CENTER ] 

Screen Shows: E : L* 



BUFFER ZERO 


o 


j 


BUFFER ZERO 


3. 


,0 


BUFFER ZERO 


a. 


► 


Delete the contents of Buffer 0. 






You Tvpe: (CLEAR)7D* (ENTER) 




Screen Shows: E : (T]D* 






BUFFER ZERO 


i < 


,0 


BUFFER ZERO 




,0 


BUFFER ZERO 


3, 


,0 


BUFFER ZERO 


a< 


,0 



Make Buffer 1 the primary buffer and Buffer the secondary 
buffer. 



You Type: B (ENTER) 
Screen Shows: E : B 

Move two lines from the primary buffer (Buffer 1) into the 
secondary buffer (Buffer 0). 

You Type: (CLEAR) 7F2 (ENTER) 
Screen Shows: E : GDP 2 

BUFFER ONE I ,0 
BUFFER ONE 2*0 

Switch to Buffer and show that the lines were moved to it. 

You Type: B0 (CLEAR)7L* (ENTER) 

Screen Shows: E:B0 (T)L* 

BUFFER ONE 1*0 
BUFFER ONE 2,0 

Switch to Buffer 1 . Go to the bottom of the buffer and get the 
text out of the secondary buffer. 
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You Type: B / G* (ENTER) 
Screen Shows: E:B / G# 

BUFFER ONE 1 . 
BUFFER ONE 2,0 

Show the contents of the buffer. Note: The order of the lines is 
changed as a result of moving the text. 



You Type: (CL 


EARJ7L* CENTER) 






Screen Shows: 


(TX* 






BUFFER ONE 


3. 


,0 




BUFFER ONE 


a. 


. 




BUFFER ONE 


i . 


,0 




BUFFER ONE 


rp 


,0 



Move two lines into the secondary buffer. 
You Type: P2 CENTER) 
Screen Shows: E : P2 

BUFFER ONE 3.0 
BUFFER ONE 4,0 

Move to the bottom of the buffer and get the lines back out of the 
secondary buffer. 

You Type: / G* [ENTER) 

Screen Shows: E : / G* 

BUFFER ONE 3,0 
BUFFER ONE 4.0 

Show that the order of the lines is restored. 
You Type: fCLEAR)7L* 
Screen Shows: E : (T)E* 

BUFFER ONE 1 ,0 

BUFFER ONE 2.0 

BUFFER ONE 3,0 

BUFFER ONE 4,0 
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Sample Session 4 



Enter some lines of text. 



You Type: (SPACEBAR) L I N E ONE CENTER) 

CSPACEBARl SECOND LINE OF TEXT 
(ENTER) 



CSPACEBAR) THIRD LINE OF TEXT 
CENTER) 



CSPACEBAR1 FQURTH LINE C ENTER) 
CSPACEBARl FIFTH LINE C ENTER) 
CSPACEBAR) LAST LINE C ENTER ) 



Screen Shows: E 

E 
E 
E 
E 
E 



LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

FOURTH LINE 

FIFTH LINE 

LAST LINE 



Open the file "oldfile 1 ' for writing. 

You Type: • WR I TE" o 1 d f i 1 e " CENTER) 
Screen Shows: E : ♦ WR I TE" o 1 d f i 1 e " 

Write all lines to the file. 



You Type: (CLEAR) 7N* [ENTER) 
Screen Shows: E zCD^* 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

FOURTH LINE 

FIFTH LINE 

LAST LINE 

*END OF TEXT* 



Close the file. 

You Type: .write// CENTER) 
Screen Shows: E:. WRITE// 

Verify that the buffer is empty. 



You Type: (CLEAR)7L* ( ENTER ) 
Screen Shows: E :GL)L* 
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Open the file * "ulclfile" " tor reading. 

You Type: . READ" o 1 df i 1 e " (ENTEfD 
Screen Shows: E : ♦ READ " o 1 d f i 1 e " 

Create a new file called ^ncwfilc"" for writing. 



You Type: ♦ WRITE" n ewf i 1 e " dNTER) 
Screen Shows: E : ♦ W R I T E " n e w f i 1 e " 

Read four lines from the input file. The screen shows the lines as 
they are read in. 

You Type: R4 dHTJERJ 
Screen Shows: E : R4 

LINE ONE 

SECOND LINE OF TEXT 
THIRD LINE OF TEXT 
FOURTH LINE 

Read all the remaining text from the file. The screen shows the 
lines. When there is no more text, the screen shows the 
*END OF FILH* message. 



You Type: R* (MSB) 
Screen Shows: E : R* 

LINE FIUE 

LAST LINE 

*END OF FILE* 

Go to the top of the buffer and display the text to make sure that 
it was inserted into the buffer. 



You Type: (CLlAR)7L* (INTER) 
Screen Shows: E : (TJL* 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

FOURTH LINE 

FIFTH LINE 

LAST LINE 

Write three lines to the output file and display the lines. 

You Type: W3 (ENTER) 

Screen Shows: E : W3 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 
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Move to the next line and display it. 
You Type: + INTER) 
Screen Shows: E : + 

FIFTH LINE 

Show that the lines are written starting at the current line and not 
at the top of the buffer. 

You Type: N (ENTER] 

Screen Shows: E s N 

FIFTH LINE 

Go to the top of the buffer and display the text to make sure that 
the lines were written to the output file. 

You Type: (CLEAR 17L* (ENTER ) 

Screen Shows: E:(jT)L* 

FOURTH LINE 
LAST LINE 

Clear the buffer. 

You Type: (CLEARE D* ( INTER] 
Screen Shows: EsQDD* 

FOURTH LINE 
LAST LINE 

Switch to Buffer 2. Open the input file ''oldfile" and read two 
lines from it. 

You Type: B2 ♦ READ" o 1 df i 1 e " R2 (ENTER) 
Screen Shows: E : B2 ♦ RE AD " o 1 d f i 1 e " R2 
LINE ONE 
SECOND LINE OF TEXT 

Switch to Buffer 1 . Open the input file l^ olclfile ,, and read one 

line oi' text. 

You Type: B ♦ RE AD " o 1 d f i 1 e " R (ENTER] 
Screen Shows: E : B ♦ R E A D " a 1 d f i 1 e " R 
LINE ONE 

Switch to Buffer 2 and read one line. Note: Your place in the file 
was not lost. 



You Type: B2 R (ENTER) 
Screen Shows: EsB2 R 

THIRD LINE OF TEXT 

Switch to Buffer I and read one line of text. Note: Your place in 
the file was not lost. 



You Type: B R (ENTER) 
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Screen Shows; E s B R 

SECOND LINE OF TEXT 

Switch to Buffer 2 and delete its contents. 



You Type: B2 (Bj-ARpD* (EBUH) 

Screen Shows: EsB2 QDD* 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

Insert some extra lines into the buffer. 

You Type: (SPA£iMR)EXTRA LINE ONE (ENTER) 
(SP ACEBARS XTR A LINE TWO (ENTER) 
Screen Shows: E : EXTRA LINE ONE 
Es EXTRA LINE TWO 

Try to write B2 buffer to file. It fails because a file has not been 
opened in this buffer. 

You Type: (CLEAR)? W* (MUB) 

Screen Shows: E :(T)W* 

*FILE CLOSED* 

Close the file for Buffer 1 and return to Buffer 2. 
You Type: B * WRITE// B2 (ENTER) 
Screen Shows: E : B .WRITE// B2 

Open the old "write" file for reading and then read it back in. 
You Type: ♦ READ "newf i 1 e " R* (ESUB) 
Screen Shows: E : . RE AD " n e w f i 1 e " R* 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

FIFTH LINE 

*END OF FILE* 

Display the contents of the buffer. Note: It read the file into the 
beginning of the buffer, since that was the position of the edit 
pointer. 
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You Type: (CLEAR) 7L* (INTER) 
Screen Shows: EsCDL* 

LINE ONE 

SECOND LINE OF TEXT 

THIRD LINE OF TEXT 

FIFTH LINE 

EXTRA LINE ONE 

EXTRA LINE TNO 



Sample Session 5 



Delete all text from the edit buffer. 

You Type: (CLEARED* (ENTER) 
Screen Shows: E : CDD* 

Insert three lines. 



You Type: (SPACEBAR) L I NE ONE (ENTER) 
(SPACEBAR) LINE TWO (ENTER) 



(SPACEBAR) LINE THREE (ENTER) 
Screen Shows: E: LINE ONE 
LINE TNO 
LINE THREE 

Create a new macro using an empty string. 
You Type: ♦MAC// (INTER) 
Screen Shows: E: ♦MAC// 

Display the contents of the macro mode, which is now open. 
Note: The H prompt is now M. 

You Type: (CLEAR) 7L* (MM) 

Screen Shows: M s (T)L* 

Define the macro. 

You Type: (SPACEBAR) F I N D CENTER) 

(SPACEBAR S" TNO" (INTER) 
Screen Shows: M: FIND 

S ,f TWO l! 
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Display the contents of the macro. 

You Type: (£LEARPL* (ENTER) 
Screen Shows: MsQjL* 

FIND 
S"TW0 M 

Close the macro's definition. 



You Type: Q (ENTER) 
Screen Shows: E s 

Display the directory of buffers and macros. 
You Type: ♦ D I R CEDE!) 
Screen Shows: 



E : • D I R 

BUFFERS: 

$ 

* 




1 


MACROS: 
FIND 





Display the contents of the edit buffer. 

You Type: CCLEAR)7L* (BEEER) 

Screen Shows: E : CD L* 

LINE ONE 
LINE TWO 
LINE THREE 

Use the FIND macro to find the string 'TWO, 
You Type: .FIND (ENTER] 
Screen Shows: E : ♦ F I ND 

LINE TWO 

Reopen the definition of the FIND macro. 



You Type: ♦ MAC/FIND/ (ENTER) 
Screen Shows: E :♦ MAC/FIND/ 

Show that the macro is still intact. 



You Type: (CLEAR) 7L* dNTfR) 
Screen Shows: M : CDL* 

FIND 
S"TW0" 
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Add the numberic parameter and the string parameter to the 
macro's header. 



You Type: C/FIND/FIND #N $STR/ [ENTER) 
Screen Shows: MsC/FIND/FIND #N $STR/ 
FIND «N $STR 

Move to the second line of the macro. 



You Type: + (ENTER) 
Screen Shows: M : + 

S !, TNO" 

Give the macro's parameters to the S command. Now the FIND 
macro will perform the same function as the S command. 
You Type: C/ M TW0"/ »N *STR/ CENTER) 
Screen Shows: M : C/ "TWO " / #N $STR 
5 #N $STR 

Close the macro's definition. 



You Type: Q (ENTER) 
Screen Shows: E : 

Display the contents of the edit buffer. 
You Type: CCLEAR) 7L* CENTER) 
Screen Shows: E : (T)L* 

LINE ONE 

LINE TWO 

LINE THREE 

Use the FIND macro to find the next two occurrences of 
"LINE." 

You Type: .FIND 2 /LINE/ CENTER) 
Screen Shows: E: .FIND 2 /LINE/ 
LINE ONE 
LINE TWO 

Create a new macro. 



You Type: .MAC// CENTER) 
Screen Shows: E : .MAC// 
M: 
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Define the macro "FIND— LINE," which performs the same 
function as the S command except that it returns the edit pointer 
to the head of the line after the last occurrence of tk STR" is 
found. 

You Type: (SPACEBAR^ I ND_L I NE #N $STR (ENTER) 
Screen Shows: M: FIND„LINE #N $STR 



You Type: (SPACEBAR' S #N $STR (BCTHD 
Screen Shows: M: S #N $STR 



Turn off the verify mode. 



You Type: dPACEBAR)^ dSHH) 
Screen Shows: M : U0 

Move the edit pointer to the first character of the current line. 
You Type: (SPACEBAR) _ JNTER) 
Screen Shows: Ms - 

Close the macro's definition. 



You Type: Q (ENTER) 
Screen Shows: M : Q 

E: 

Di splay the contents of the edit buffer. 



You Type: (CLlAR)7L* dHUI) 
Screen Shows: EsGDL* 

LINE ONE 
LINE TWO 
LINE THREE 

Use the "FIND—LINE" macro to search for the string 

"TWO." 

You Type: * F I ND„L I NE/TNO/ (MSS) 
Screen Shows: E : ♦ F I ND-LINE/TWO/ 
LINE TWO 

Show that the "FIND—LINE" macro left the edit pointer at the 
head of the line. 



You Type: L (ENTER) 
Screen Shows: E : L 



LINE TWO 
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Create a new macro. 

You Type: .MAC// dNTER) 
Screen Shows: E : . MAC/ / 
M: 

Use the exclamation point (!) command to comment itself. Type 
the following: 

Ms CONVERT_TQ_LINES *N 

Ms ! This is a comment 

Ms ! 

Ms ! This macro concerts 
the next n 

Ms ! space characters to new line 

Ms ! characters* 

M s { J ! T s.i r n u e r i f y m ode 

off 

Ms ! t o p r e m e n t 1 n t e r - 

mediate results 

Ms ! froin beind 

displayed* 

Ms ! 

M : [ ! Be^in loop 

Ms * SEARCH/ / ! Search for < space > 
character* 

Ms i / / ! Insert empty 

line ( n e w 1 i n e 
character) * 

Ms- ! Back up one line. 

MsC/// ! Delete the 
next space 
character* 
B h o w line* m o l.j e 
past i t * 
End of loop. 
Repeat # N times* 





Ms 


L 


+ 






Ms 


] 


»N 




Cl< 


;)sc the macro's dc 
You Type: Q 
Screen Shows: 


finition. 
(IFfERJ 

MsQ 
Es 
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Display the contents of the edit buffer. 
You Type: (CLEAR)7L* CENTER) 
Screen Shows: E : (TjL* 

LINE ONE 

LINE TWO 

LINE THREE 

Convert all space characters to new line characters. Note: The 
loop stops when the C command in the macro cannot find a 
space to delete. 

You Type: . CONUERT-TO-L I NES * (ENTER) 

Screen Shows: E : ♦ CONUERT„TO_L I NES * 

LINE 

LINE 

LINE 

Display the contents of the edit buffer. 



You Type: (CLEAR)? L* (ENTIH) 
Screen Shows: E s (T)L* 

LINE 

ONE 

LINE 

TWO 

LINE 

THREE 
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Appendices 

Appendix A / Glossary 



BUFFER 
EDIT POINTER 

MACRO 

PATHLIST 
PSEUDO MACRO 

TEXT FILE 
WORKSPACE 



Holding area in memory for text. 

Internal marker the editor uses to 
remember your position in the edit 
butler. 

New command you may define; it is 
composed of existing commands. Use 
macros to repeat the same command 
sequence over and over again. 

See the OS -9 Commands. 

Command that is part of the EDIT pro- 
gram and written in assembly language 
that is used as if it were a macro. 

Place where OS-9 keeps the text that 
you want saved. 

Available memory pool that the editor 
uses for buffers and macros. 



Appendix B / Quick Reference Summary 



EDIT OS-9 loads the editor and starts it. 

There are no initial read or write files. 
Perform text- file operations by opening 
files after the editor is running. 

EDIT newfile Unewfile does not exist, OS-9 loads the 

editor and starts it. The editor creates a 
file called newfile, and this is the initial 
write file. There is no initial read file; 
however, files may be read if they are 
opened after the editor is started. 
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EDIT old file 



KDIT oidfile newfile 



OS-9 loads the editor and starts it. The 
initial read tile is oidfile. The editor 
ereates a new file called SCRATCH; 
this is the initial write file. When the 
edit session is complete, oidfile is de- 
leted, and SCRATCH is given the 
name oidfile. 

OS-9 loads the editor and starts it. The 
initial read file is oidfile. The editor 
creates a tile called ne\vfdt\ and this is 
the initial write Hie. 



Edit Commands 



.MACRO 



(SPAC EBAR] 
CENTER) 

+ n 



+ 



-0 



>// 



Executes the macro specified by the 
name following the period (.). 

Places comments inside a macro and 
ignores the remainder of the command 
line. 

Inserts line before the current position 
of the edit pointer. 

Moves the edit pointer to the next line 
and displays it. 

Moves the edit pointer forward n lines 
and displays the line. 

Moves the edit pointer backward n lines 
and displays the line. 

Moves the edit pointer to the last char- 
acter of the line. 

Moves the edit pointer to the first char- 
acter of the current line and displays it. 

Moves the edit pointer forward n 
characters. 
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<n 



(CLEAR) 7 



Moves the edit pointer backward n 
characters. 

Moves the edit pointer to the beginning 
of the text. 



[commands] n 



An 



AC) 



Qn strl str2 

Dn 
En str 

G/7 



\n str 



Moves the edit pointer to the end of the 
text. 

Repeats the sequence of commands be- 
tween the two brackets n times. 

Skips to the end of the innermost loop 
or macro if the fail flag is not on. 

Sets the SEARCH/CHANGK anchor to 
Column iu restricting searches and 
changes to those strings starting in the 
Column n. This command remains in 
effect for the current command line. 

Returns the anchor to the normal mode 
of searching so that strings are found 
regardless of the column in which they 
start. 

Makes buffer // the primary buffer. 

Changes the next n occurrences of 
string! to string!. 

Deletes n lines. 

Extends (adds the string to the end of) 
the next n lines. 

Gets n lines from the secondary buffer, 
starting from the top. Inserts the lines 
before the current position in the prim- 
ary buffer. 

Inserts a line containing n copies of the 
string before the current position of the 
edit pointer. 
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Kn Kills n characters starting at the current 

position of the edit pointer. 

L/7 Lists (displays) the next n lines, starting 

at the current position of the edit 
pointer. 

Mn Changes workspace (memory) size to n 

bytes. 

Pn Puts (moves) n lines from the position 

of the edit pointer in the primary buffer 
to the position of the edit pointer in the 
secondary buffer. 

Q Quits editing (and terminates editor). If 

you specified file(s) when you entered 
EDIT, Buffer 1 is written out to the 
output file. The remainder of the input 
file is copied to the output file. All files 
are closed. 

R/7 Reads n lines from the buffer's input 

file. 

S// str Searches for the next n occurrences of 

the string. 

Yn Tabs to Column n of the present line. If 

n is greater than the line length, the line 
is extended with space. 

U Unextends (truncates) line at the cur- 

rent position of the edit pointer. 

\modc Turns the verify mode on or off. 

W/7 Writes n lines to the buffer's output 

file. 

Xn Displays n lines that precede the edit 

position. The current line is counted as 
the first line. 
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Pseudo Macros 



.CHANGE 

n strl strl 

DEL str 
.DIR 

.EOB 
.EOF 
.EOL 
.F 

.LOAD str 

.MAC str 

.NEOB 
.NEOL 
.NEW 



.NSTR str 



READ str 



Changes n occurrences of strl to strl. 

Deletes the macro specified by string. 

Displays the directory of buffers and 
macros. 

Tests for the end of the buffer. 

Tests for the end of the file. 

Tests for the end of the line. 

Exits the innermost loop or macro and 
sets the fail flag. 

Loads macros from the path specified 
in the string. 

Opens the macro specified by the string 
for definition. If an empty string is 
given, a new macro is created. 

Tests for not end of buffer. 

Tests for not end of file. 

Writes lines out to the initial output file 
up to the current line and then attempts 
to read an equal amount of text from the 
initial input file. The test read-in is 
appended to the end of the edit buffer. 

Tests to see if string does not match the 
characters at the current position of the 
edit pointer. 

Opens an OS-9 text file for reading, 
using string as the pathlist. 

Exits the innermost loop or macro and 
succeeds (clears the fail flan). 
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.SEARCH // str 
.SAVE str I str2 



.SHELL 

command line 



.SIZE 



.STAR n 



STR str 



.WRITE str 



ZERO n 



Searches for n occurrences of str. 

Saves the macros specified in string 1 
on the file specified by the pathlist in 
string . 

Calls OS-9 shell to execute the com- 
mand line. 

Displays the size of memory used and 
the amount of memory available in the 
workspace. 

Tests to see if n equals asterisk 
(infinity). 

Tests to see \{ string matches the char- 
acters at the current position of the edit 
pointer. 

Opens an OS-9 text for writing, using 
string as a pathlist. 

Tests n to see if it is zero. 



(J) 

type [CLEAR)7 



Starts at a macro loop; type (CLEAR] 9. 

Ends at a macro loop; TYPE [CLrAR^. 

Moves edit pointer io beginning of 
buffer; 



Appendix C / Editor Error Messages 



BAD MACRO 

NAME 



BAD NUMBER 



The first line in the macro does not 
begin with a legal name. You can close 
the definition of a macro after you give 
it a legal name. 

You have entered an illegal numeric 
parameter, probably a number greater 
than 65,535. 
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BAD VAR NAME 



BRACKET 
MISMATCH 

BREAK 



DUPL MACRO 



END OF FILE 
FILE CLOSED 



MACRO IS OPEN 



MISSING DELIM 



NOT FOUND 



UNDEFINED VAR 



You have specified an illegal variable 
name. Usually, you omitted the vari- 
able name or inadvertently included a 
$ or # character in the commands 
parameter list. 

You have not entered brackets in pairs 
or the brackets are nested too deeply. 



You typed (CONTRO Dm or 
[CONTROL] fCD to interrupt the editor. 
After printing the error message, the 
editor returns to command entry mode. 
Note: Results may not be displayed 
during command operation. 

You attempted to close a macro defini- 
tion with the same name as another 
macro. Rename the macro before 
trying to close its definition. 

You are at the end of the edit buffer. 

You tried to write to a file that was 
never opened. Either specify a write 
file when starting the editor from OS-9, 
or open an output file using the 
.WRITE pseudo macro. 

Close the macro definition before using 
the command that caused this error. 

The editor could not find a matching 
delimiter to complete the string you 
specified. You must put the string com- 
pletely on one line. 

The editor cannot find the specified 
string or macro. 

You used a variable thai was not speci- 
fied in the macro's definition parameter 
list. A variable parameter may be used 
only in the macro in which it is 
declared. 
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WHAT '.'? The editor did not understand a com- 

mand you typed. This is usually caused 
by entering a command that does not 
exist (misspelling its name). 

WORKSPACE: FULL The buffer did not have room for the 
text you attempted to insert. Increase 
the workspace or remove some text. 
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OS-9 Assembler 



1 / Introduction 



The machine instructions executed by a computer are se- 
quences of binary numbers that are difficult for people to deal 
with directly. Creating a machine-language program by hand 
is tedious, error prone, and time consuming. Assembly lan- 
guage bridges the gap between computers and machine- 
language programmers. 

Assembly language uses descriptive mnemonics (abbrevia- 
tions) for each machine instruction instead of numerical 
codes. These arc much easier to learn, read, and renumber. 
The assembler also lets the programmer assign symbolic 
names to memory addresses and constant values. 

This assembler is designed expressly for the modular, multi- 
tasking environment of the OS-9 Operating System and in- 
corporates built-in functions for calling OS-9, generating 
memory modules, encouraging the creation of position- 
independent-code, and maintaining separate program and data 
sections. It is also optimized for use by OS-9 high-level lan- 
guage compilers such as Pascal and C. 

The OS-9 assembler is extremely fast as a result of its tree- 
structured symbol table organization. This dramatically re- 
duces the time for symbol table searching. 

This manual describes how to use the OS-9 Assembler and 
explains basic programming techniques for the OS-9 environ- 
ment. It is not a comprehensive course on assembly language 
programming or the 6809 instruction set. 

If you are not familiar with these topics, consult the Motorola 
6809 programming manuals and one of the many excellent 
assembly-language programming books available at libraries 
and bookstores. 



Installation 



The OS-9 Assembler distribution disk contains the asm file 
(the assembler program) and the DEFS file (a directory con- 
taining OS-9 common system-wide definition files; see ehap- 
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tcr 7). These files are OSQDefs, SysTypc. SCFDefs, and 
RBFDefs. 

Copy the asm file to the CMOS directory of your system 
disk. Create a directory on your system disk called DEFS (if 
not already present) and copy the four DFFS files to it. Place 
the assembler distribution disk in Drive 1 and your system 
disk in Drive 0. Use the following commands. 

eopy/d 1 /'asm/dO/cmds/asm # 1 2k 

makdir /d()/I)FFS 

copy /dl/defs/os9defs /d()/det"s/os9defs #12k 

copy /dl/defs/systype /d()/defs/systype #12k 

copy 'dl/defs/scfdefs /d()/defs/scfdefs #12k 

copy /dl/defs/rbfdefs /d()/defs/rbfdefs # 1 2k 



Assembly Language Program Development 



Writing and testing assembly language programs involves a 
basic edit-assemble-test cycle. 

1. Create a source program file using the text editor. 

2. Run the assembler to translate the source file to a 
machine-language file. 

3. If the assembler reports errors, use the text editor to cor- 
rect the source file. Go back to step 2. 

4. Run and test the program, using the OS-9 Interactive 
Debugger. 

5. If the program has bugs, use the text editor to correct the 
source file. Go back to step 2. 

6. Document the program. 
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Assembler Input Files 



The OS-9 Assembler reads from an input file (path) that con- 
tains variable-length lines of ASCII characters. You can cor- 
rect and edit input files with the OS-9 Macro Text Editor or 
with any other standard text editor. 

The maximum length of the input line is 120 characters. Each 
line contains assembler statements as explained in this man- 
ual. Terminate every line by typing (E NTER) . 

Running the Assembler 



The assembler is a command program that can be run from 
the OS-9 Shell, from a shell procedure file, or from another 
program. The disk file and memory module names are ASM. 
The following is the basic format of a command line to run 
the assembler: 

asm file name [option(s)] [~#memsize] [ >listing ] 

Brackets enclose options; therefore, the only required items 
are the ASM command name and the file name, which is the 
source text file name (pathlist). The following is a typical 
command: 

asm prog5 Is -c #!2k >/p 

In this example the source program is read from the file 
PROG5. The source file name can be followed by an option 
list, which allows you to control various factors such as 
whether or not to generate a listing or an object file. 

The option list consists of one or more abbreviations sepa- 
rated by spaces or commas. An option is turned on by its 
presence in the list; a minus followed by an option abbrevia- 
tion turns off the function. If an option is not expressly given, 
the assembler assumes a default condition for it. 
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You can override command options by OPT statements with- 
in the source program. In the example above, the options 1 
and s are turned on, and c is turned off. 

The shell processes the optional #memsize item to specify 
how much data area memory the assembler is assigned. If this 
is not specified, the assembler is assigned 4K bytes of mem- 
ory in its data area. Most of this space is used to store the 
symbol table. Any additional memory that this option re- 
quests enlarges the symbol table. 

Large programs generally use more symbols; therefore, their 
memory requirements are correspondingly greater. If the 
assembler generates the * 'Symbol Table Full 1 ' error message, 
increase the assembler's memory size. In the previous exam- 
ple, 12K bytes of memory are specified. 

The final item, ik >Iisting , \ allows the program listing gener- 
ated by the assembler (on the standard output path) to be 
optionally redirected to another pathlist, which may be an 
output device such as a printer, a disk file, or a pipe to 
another program. 

The shell handles the memory size option, and it handles out- 
put redirection, not the assembler. If you omit this item from 
the command line, your screen shows the output. In the 
above example, the listing output is directed to device p, the 
printer on most OS- systems. 



Operating Modes 



The OS-9 Assembler has a number of features specifically 
designed to conveniently develop machine-language programs 
for the OS-9 environment. These include special assembler 
directive statements for generating OS-9 memory modules, 
identification of 6809 addressing modes that are not usually 
permitted in OS-9 programs, and separate data and program 
address counters. 

The assembler has two operating modes — normal and 
Motorola-compatible. In normal mode, the features men- 
tioned above are active. In the Motorola-compatible mode, 
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the assembler works the same way as a standard 6809 "abso- 
lute"' assembler (without separate program and data count- 
ers). This mode exists so that you can use the assembler to 
generate programs for 6809 computers that are not equipped 
with OS-9. 

The assembler is in the normal mode unless you use the m 
option in the command line or in an OPT statement. 
The -m option returns the assembler to the normal mode (you 
can switch modes freely to achieve special effects). 

The assembler performs two "passes" (complete scans) over 
the source file. During each pass, it reads input lines and 
processes them one at a time. During the first pass, it creates 
the symbol table. It generates most error messages, the pro- 
gram listing, and the object code during the second pass. 
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2 / Source Statement Fields 



Label Field 



Each input line is a text string that you terminate by typing 
(ENTER] . The line can have from one to four fields — a label 
field, an operation field, an operand field (for some opera- 
tions), and a comment field. 

If you type an asterisk as the first character of a line, the 
assembler treats the entire line as a comment. It displays it in 
the listing but does not otherwise process it. The assembler 
ignores blank lines but includes them in the listing. 



The label field begins in the first character position of the 
line. Some statements require labels (for example, HQU and 
SET); others (assembler directives such as SPC, TTL) must 
not have them. The first character of the line must be a space 
if the line does not contain a label. 

The label must be a legal symbolic name consisting of from 
one to eight upper- or lower-ease characters, decimal digits, 
or the characters dollar sign ($), underline (__), or dot (.); 
however, the first character must be a letter. You must not 
define labels (and names in general) more than once in a 
program (except when used with the SET directive). 

The symbol table stores label names with an associated 16-bit 
value, which is normally the program counter address before 
code is generated for the line. In other words, instructions 
and most constant-definition statements associate the label 
name with the value of the program address of the first object 
code byte generated for the line. 

An exception to this rule is that labels on SET and EQU 
statements are given the value of the result of evaluation of 
the operand field. In other words, these statements allow any 
value to be associated with a symbolic name. 

Likewise, labels on RMB statements are given the value of 
the data address counter when in normal assembler mode, or 
the value of the program address counter when in Motorola- 
compatible mode. 



77 



Operation Field 



This field specifies the machine-language instruction or 
assembler directive statement mnemonic name. It immediate- 
ly follows and is separated from the label field by one or 
more spaces. 

Some instructions must include a register name that is part of 
the operation field (for example, LDA, LDD, LDU). In these 
instructions the register name must be part of the name and 
cannot be separated by spaces as in older 6800-type assem- 
blers. The assembler accepts instruction mnemonic names in 
cither upper- or lower-case characters. 

Instructions generate one to five bytes of object code, de- 
pending on the specific instruction and addressing mode. 
Some assembler directive statements (such as FCB, FCC) 
also generate object code. 



Operand Field 



The operand field follows and must be separated by at least 
one space from the operation field. Some instructions do not 
use an operand field; other instructions and assembler direc- 
tives require one to specify an addressing mode, operand, 
address, parameters, and so on. 



Comment Field 



The comment field is the last field of the source statement 
and is used to include a descriptive comment. It is optional. 
The assembler does not process this field but copies it to the 
program listing. 
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3 / Symbolic Names and 
Expressions 

Evaluation of Expressions 



Operands of many instructions and assembler directives in- 
clude numeric expressions in one or more places. The 
assembler can evaluate expressions of almost any complexity, 
using a form similar to the algebraic notation in programming 
languages such as BASIC and FORTRAN. 

Hxpressions consist of operands, which are symbolic names 
or constants, and operators, which specify an arithmetic or 
logical function. All assembler arithmetic uses two-byte (in- 
ternally. 16-bit binary) signed or unsigned integers in the 
range of to 65535 for unsigned numbers and — 32768 to 
+ 32767 for signed numbers. 

In some cases, expressions are expected to evaluate to a value 
that must fit in one byte (such as 8-bit register instructions) 
and therefore must be in the range of to 255 for unsigned 
values and - 128 to 127 for signed values. In these cases, if 
the result of an expression is outside this range, the screen 
shows an error message. 

The assembler evaluates expressions from left to right, using 
the algebraic order of operations (that is, it multiplies and 
divides before it adds and subtracts). Parentheses alter the 
natural order of evaluation. 



Expression Operands 



You may use the following items as operands within an 
expression. 

Decimal Numbers, Optional minus sign ( - ) and one to five 
digits. Examples: 

100 

32767 



12 
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Operators 



Hexadecimal Numbers. Dollar sign ($) followed by one to 
four hexadecimal characters (0-9, A-E, or a-f). Examples: 

SEC00 

$1000 

$3 
$0300 

Binary Numbers. Percent sign ( r /r) followed by one to six- 
teen binary digits (0 to 1). Examples: 

<7r() 10 1 

%111 1000011110000 

7.10101010 

Character Constants. Single quote f) followed by any 
printable ASCII character. Examples: 

X 

'c 
\5 



Symbolic Names. One to eight characters, upper- and lower- 
case alpha (A-Z or a-z), digits (0-9), and special characters 
., or $ (underscore, period, or dollar sign). The first char- 
acter cannot be a digit. 

Instruction Counter. Placed at the beginning of the line, the 
asterisk (*) represents the program instruction counter value. 

Data Counter. Placed at the beginning of the line, the period 
(.) represents the data storage counter value. 



''Operators" specify arithmetic or logical operations to be 
performed within an expression. The assembler executes 
operators in the following order: (1) -, negative numbers; 
(2) & and !, logical AND and OR; (3) * and /, multiplication 
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and division; (4) 4- and - , addition and subtraction. Oper- 
ators in a single expression having equal precedence, for ex- 
ample, 4- and - , are evaluated left to right. You can use 
parentheses, however, to override precedence. 

Assembler Operators by Order of Evaluation 

- negative A logical NOT 

& logical AND ! logical OR 

* multiplication / division 

4- addition - subtraction 

Logical operations are performed bitwise; that is, the logical 
function is performed bit by bit on each bit of the operands. 

Division and multiplication functions assume unsigned oper- 
ands, but subtraction and addition work on signed (2's com- 
plement) or unsigned numbers. The screen shows an error 
message if you attempt to divide by zero or multiply by a 
factor that results in a product larger than 65, 536. 



Symbolic Names 



A symbolic name consists of from one to eight upper- or 
lower-case characters, decimal digits, or the dollar sign ($), 
the underline (_), or the dot (.); however, the first character 
must be a letter. The following are examples of legal symbol 
names: 

HERE 

there 

SPL030 

VX_GH 

abc.def 

Q 1020.1 

L. 123.X 

t$integer 
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These are examples of illegal symbol names: 

2move (does not start with a letter) 

main. backup (has more than eight characters) 
lbl#123 (contains #, which is not a legal name 

character) 

You define a name the first time you use it as a label on an 
instruction or directive statement. You can define a name 
only once in the program (except SET labels). If you redefine 
a name (use as a label more than once), the screen shows an 
error message. You cannot use multiple forward references 
(that is, a definition using currently undefined names). 

The symbol table stores symbolic names with their associated 
type and value. This structure uses most of the assembler's 
data memory space. Using the default memory size of 4K, 
the symbol table has room for approximately 200 names. 

You can use the shell's optional memory size modifier to 
increase the assembler's memory space. Each entry in the 
table requires 15 bytes; therefore, each additional 4K of 
memory adds space for about 273 additional names. 

For example, the command line 

asm sourcefile #16K 

gives the symbol table enough space lor a little more than a 
thousand names. If you select the S option, the assembler 
generates an alphabetical display of all symbol names, types, 
and values at the end of the assembly. 
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4 / Instruction Addressing Modes 



The instruction set has a wide variety of addressing modes. 
Each group of similar instructions is used with specific 
addressing modes, which are usually specified in the assem- 
bler source statement operand field. The assembler generates 
an error message if an addressing mode is specified that can- 
not legally be used with the specific instruction. 



Inherent Addressing 



Certain instructions do not need operands (for example, 
SYNC and SWI); others implicitly specify operands (for ex- 
ample, MUL and ABX). In these cases no operand field is 
needed. 



Accumulator Addressing 



Some instructions have the A or B accumulators as operands. 
Examples: 

CLRA 
ASLB 
INC A 



Immediate Addressing 



In immediate addressing, the instruction uses the operand 
bytes as the actual value. Instructions that use 8-bit registers 
must have operand expressions that evaluate in the range of 
to 255 (unsigned) or - 128 to 127 (signed). If they do not, 
the screen shows an error message. 

The syntax is: 

instr #expression 



83 



Lxamples: 



LOO #$1F()<) 
ldb #bufsiz I 2 
ORCC #$FFCBir 



Relative Addressing 



Branch-type instructions, such as BCC. BFQ, LBNF, BSR. 
and LBSR, use the relative addressing mode. The operand 
field is an expression that is the ^destination" of the instruc- 
tion, which is almost always a name used as a statement label 
somewhere in the program. 

The assembler computes an 8- or 16-bit program counter 
offset to the destination, which is made part of the instruc- 
tion. If the destination of short branch-type instructions is not 
in the range of - 126 to f 1 29 bytes of the instruction 
address, the screen shows the error message. 

Long branch-type instructions can reference any destination. 
If a long branch instruction references a destination that is 
within the range of a smaller and faster short branch instruc- 
tion, the assembler places a warning symbol (W) in the listing 
line's information field. All instructions using relative address- 
ing are inherently position independent code, Lxamples: 



BCS 


LOOP 


LBNE 


LABKL5 


LBSR 


START f 3 


BLT 


COUNT 



Extended and Extended Indirect Addressing 



Extended addressing uses the second and third bytes of the 
instruction as the absolute address of the operand. Data sec- 
tion addresses of OS-9 programs arc assigned when the pro- 
gram is actually executed; therefore, absolute memory 
addresses are not known before the program is run, and this 



84 



addressing mode is not normally used in OS-9 programs. The 
screen shows an informational warning flag (W) if this 
addressing mode is specified. 

Extended indirect addressing is similar to extended addressing 
except that the address part of the machine instruction is used 
as the address of a memory location containing the address of 
the operand. 

Because this mode also uses absolute addresses, it is not fre- 
quently used in OS-9. and the assembler flags it with a warn- 
ing. Select this addressing mode by enclosing the address 
expression in brackets. Examples: 

ADDA SIC48 extended addressing 

ADDA [SD58AJ extended indirect addressing 

LBD START extended addressing 

stb lend | extended indirect addressinu 



Direct Addressing 



Direct addressing uses the second byte of the instruction as 
the least significant byte of the operand's address. The most 
significant byte is obtained from the MPUs direct page 
register. 

This addressing mode is preferred for accessing most vari- 
ables in OS-9 programs because OS-9 automatically assigns 
unique direct pages to each task at run time and because this 
mode produces short, fast instructions. 

The syntax for extended and direct addressing has the same 
form: 

instr * -addr expr - 

The assembler automatical!) selects direct addressing mode if 
the high-order byte of the address matches its internal "direct 
page/' This direct page is not the same as the run-time direct 
page register; it is an assembly-time value. You ordinarily set 
it to zero, but vou can chamze it with the SHTDP directive. 
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You can force the assembler to use direct addressing by typ- 
ing the less than symbol (<) just before the address expres- 
sion or to use extended addressing by typing the greater than 
symbol <>) just before the address expression. Examples: 

Ida temp (assembler selects mode) 

LDD ---PA1+1 (forces extended addressing) 

Idx * count (forces direct addressing) 

STI) | pointer] (extended indirect) 



Register Addressing 



Some instructions operate on various MPU registers, which 
are referred to by a one- or two-letter name. In these instruc- 
tions the operand field specifies one or more register names. 
The names, which can be upper- or lower-case, arc: 

A accumulator A (8 bits) 

B accumulator B (8 bits) 

D accumulator A:B concatenated (16 bits) 

DP direct page register (8 bits) 

CC condition codes register (8 bits) 

X index register X (16 bits) 

Y index register Y (16 bits) 

S stack pointer register (16 bits) 

U user stack pointer register (16 bits) 

PC program counter register (16 bits) 

The EXG and TFR instructions have the form: 

in sir reg,reg 

If the registers are not the same size (either 8 or 16 bits), the 
screen shows the error message. 

The PSHS, PSHU, PULS, and PULU instructions accept a 
list of one or more register names. Even though the assembler 
accepts register names in any order, the MPU stacks and un- 
stacks them in a specific order. 
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The syntax for these instruetions is 

instr rei>{,reg] 
Examples: 

TFR X,Y 

EXG A. DP 

pshs a,b,x,dp 
PULU d,x.pc 



Indexed Addressing 



The 6809 has 23 varieties of indexed addressing modes. In- 
dexed addressing is analogous to "register indirect/' mean- 
ing that an indexable register (X, Y, U, S, or PC) is used as 
the basic address of the instruction's operand. 

The different varieties of indexed addressing use the specified 
register contents, which may be unchanged, temporarily mod- 
ified, or permanently modified, depending on the mode. 

All indexed modes must specify an index register, either X, 
Y, U, or SP. You can use the Register PC with the program- 
counter relative mode only. 

To make any indexed addressing mode "indirect/' enclose 
the operand field in brackets. The effective address generated 
by the addressing mode is used as the address of a pointer to 
the operand rather than as the address o\ the operand. 



Constant Offset Indexed 



This mode uses an optional signed {two's complement) offset 
that is temporarily added to the register's value to form the 
operand's effective address. The offset can be any number: if 
it is zero, the register's unaltered content is used as the effec- 
tive address. The assembler automatically picks the shortest 
of four possible varieties that can represent the offset. 
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If a symbolic name used in the offset expression is not de- 
fined, the assembler generates longer code than necessary or 
produces phasing errors. 

The syntax for constant offset indexed instructions is; 



instr 


,reg 


zero offset 


instr 


offset, re n 


constant offset 


instr 


[.regj 


zero offset indirect 


instr 


[offset, re u] 


constant-offset indirect 



Kxamples: 



Ida 


,x 


no offset 


Ida 


0,x 


no offset 


ldx 


100, x 


offset of 100 


LDB 


COUNT, S 


offset of COUNT 


kid 


temp + 2,y 


offset oi temp 4- 2 


leax 


-2,y 


offset of - 2 


clr 


[PIA,Xl 


indirect mode 



Program Counter Relative Indexed 



This addressing mode is similar to constant-offset indexed ex- 
cept that the program counter register (PC or PCR) is used as 
an index register, and the assembler computes the offset dif- 
ferently. Instead of tising the offset expression directly, the 
expression is assumed to refer to the address of the operand. 

The assembler calculates the required offset from the current 
program counter location to the operand's address and uses 
the resulting value as the offset. One form of this instruction 
uses an 8-bit offset and the other uses a 16-bit offset. The 
assembler uses the 16-bit form unless you force the short 
form by typing the less than symbol (<) before the operand 
field. 

The syntax for program-counter relative indexed is: 

instr addr,PC program counter relative 

instr addr,PCR program counter relative 

instr [addr,PCR] program counter relative indirect 

instr [addr,PC] program counter relative indirect 
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This addressing mode permits addresses of constants and con- 
stant tables to be accessed using position independent code as 
required by OS-9. 

Examples: 

Idd temp, per 

LDD temp,pc same as instruction above 

leax table, per 

jsr addr,pcr same as "ibsr addr" 

CLR [control I 4,PCRl dangerous; uses absolute 

address at "control + 4, PCR" 
as e fleet ive address ("or clear 



Accumulator Offset Indexed 



In this mode the contents of the A, B, or D accumulators are 
temporarily added to the specified index register to form 
the address of the operand. This addition is signed two's 
complement. 

If you specify the A or B accumulators, the sign bit is "ex- 
tended" to form the 16-bit value, which is added to the index 
register. This means that if the most significant bit of the 
accumulator is set, the high order byte of the offset is $FF. 

Beware: This is a commonly overlooked characteristic that 
can produce unexpected results! Using the D register avoids 
this because it gives all 16 bits. 

The syntax for accumulator-offset indexed is: 

instr A,reg 
instr B,reg 
instr D,reg 

Examples: 

LDX B,Y 
LHAY D,X 

ROL |B,U] 
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Auto-Increment and Auto-Decrement Indexed 



These addressing modes use the specified index register as 
the effective address of the operand while permanently adding 
or subtracting one or two from the register. In auto-increment 
mode, the increment is performed after the register is used. In 
auto-decrement mode, the decrement is performed before the 
register is used. This is consistent with the way 6809 stack 
pointers operate in PSH and PUL instructions. 

If you use indirect addressing, the decrement and increment 
are performed before the effective address is used as a pointer 
to the operand. You cannot use single auto-increment and 
single auto-decrement when you select indirect addressing. 

Syntax for auto-increment and auto-decrement indexed 
addressing is: 

single auto-decrement 
double auto-decrcment 
single auto-increment 
double auto-increment 
double auto-decrement indirect 
double auto-increment indirect 

Examples: 

clr ,x + + 

LDX , - - Y 

Ida ,s f is the same as puis a (except CCR is affected) 

sta , - sis the same as pshs a (except CCR is affected) 

ldd [,s++] 



instr 


,-rcg 


instr 


, reg 


instr 


,rcg + 


instr 


,reg + + 


instr 


l>eg- -] 


instr 


[\reg++] 
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5 / Pseudo Instructions 



Pseudo instructions arc special assembler statements that 
generate object code but do not correspond to actual 6809 
machine instructions. Their primary purpose is to create spe- 
cial sequences of constant data to be included in the program. 
Labels are optional on pseudo instructions. 



FCB <expression> {, <expression>] 



generates sequences of single byte constants (FCB) within the 
program. The screen shows the error message if an expres- 
sion has a value of more than 255 or less than — 128 (the 
largest number that can be represented by a byte). 



FDB <expression> {, <expression>\ 



generates sequences of" double byte constants (FOB) within 
the program. If this statement evaluates an expression with an 
absolute value of less than 256, the high order-byte is zero. 

The operand is a list of one or more expressions that are 
evaluated and output as constants. To generate more than one 
constant, separate the expressions with commas. 

F^xamples; 

FCB 1,20, A 

feb index/2 + 1.0,0,1 

FBD 1,10,100,1000,10000 

fdb $F900.SFA00,$FB00,$FC00 



FCB 'A 
FDB <CN' 

FCB 4 ? + 80 
FCC string 
FCS string 



generate a series oi' bytes corresponding to a specified string 
of one or more characters operand. 
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The output bytes are the literal numeric value of" each ASCII 
character in the specified string. PCS ts the same as FCC 
except the most significant bit (the sign bit) of the last charac- 
ter in the specified string is set. This is a common OS-9 
programming technique to indicate the end of a text string 
without using additional storage. 

You must enclose the characters in the specified string 
with delimiters. You can use the following characters as 
delimiters: 

!" #$</,&'() * f , - . / 

The delimiters must be identical, and you cannot include 
them in the string itself. Examples: 

FCC /most programmers are strange people/ 

FCS ,0123456789, 

fee S/S 



MOD size,nameoff,typelang,attrrev {,execoff,memsize} 



creates a standard OS-9 module header and initializes a CRC 
(cyclical redundancy cheek) value that the assembler auto- 
matically computes as it processes the program. 

OS-9 can load programs into memory only if they are in 
module header format. You use the MOD statement at the be- 
ginning oi" an OS-9 module. It must have an operand list of 
exactly four or exactly six expressions separated by commas. 
Faeh operand corresponds, in order, to the elements of a 
module header. The exact operation of the MOD statement is 
as follows: 

1. Resets the assembler's program address counter and data 
address counters to zero (same as ORG 0) and initializes 
the internal CRC and vertical parity generators. 

2. Generates the syne codes $87 and $CD as object code. 
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EMOD 



3. Evaluates and outputs as object code the first four expres- 
sions in the operand list. They are: 

a. module size (two bytes) 

b. module name offset {two bytes) 

c. type-language byte (one byte) 

d. attribute-revision byte (one byte) 

4. Computes the header parity byte from the previous bytes 
and generates it as object code. 

5. Evaluates the two optional additional operands if they are 
present and generates them as object code. They are: 

e. execution offset 

f. permanent storage size 

Note: Some expressions in the operand list are one byte long, 
and others are two bytes. 

Because the origin of the object program is zero, all labels 
used in the program are inherently relative to the beginning of 
the module. This is perfect for the module name and execu- 
tion address offsets. The code in the body of the module fol- 
lows. As subsequent lines are assembled, the internal CRC 
generator continuously updates the module's CRC value. 



terminates the module. 

The EMOD statement has no operand. It outputs the correct 
three-byte CRC generated over the entire module. 

Note: The MOD and EMOD statements do not work correct- 
ly if the assembler is in Motorola-compatible mode unless 
you do not use RMB or ORG statements after the MOD and 
before the EMOD. 

The example below illustrates the basic techniques of creating 
a module using MOD and EMOD statements. 

type set PRGRM + OBJCT (these are defined in 

OS9DEFS) 



93 



set RFFNT f- 1 (this is defined in 

OS9DHFS) 
MOD pgmlen, name Jypc, re vs. start, memsize 

::: data storage declarations 



temp 


RMB 1 


addr 


RMB 2 


buffer 


RMB 500 


stack 


RMB 250 


niemsiz 


EQU data storage si/e is fina 


name 


FCS /textmodule/ 


start 


leax buffer, u get address of buffei 




elr temp 




inc temp 




Idd #500 loop count 


loop 


clr ,x + 




subd #1 




bne loop 




os9 FSBXIT return to OS9 




FMOD 



pg ml en HQU * program size is addr of last byte + 1 

OS9 <expression> 

generates OS-9 system calls. 

This statement has an operand that is a byte value to be used 
as the request code. The output is equivalent to the instruction 
sequence: 

SW12 

FCB operand 
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The OS9Defs file contains standard definitions of the sym- 
bolic names of all OS-9 service requests. You can use these 
names in conjunction with the OS9 statement to improve the 
readability, portability, and maintainability of assembly- 
language software. 

Examples: 

OS9 ISRead (call OS-9 READ service request) 

OS9 F$Exit (call OS-9 EXIT service request) 
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6 / Assembler Directive Statements 



END 



Assembler directive statements give the assembler infor- 
mation that affects the assembly process but that does not 
generate code. Read the descriptions carefully because some 
directives require labels, labels are optional on others, and a 
few cannot have labels. 



indicates the end of a program. 

The use of this statement is optional since END is assumed 
upon an end-of-file condition on the source file. End state- 
ments may not have labels. 



label EQU <expression> 
label SET <expression> 



assign a value to a symbolic name (the label). 

The value assigned to the symbol is the value of the operand, 
which may be an expression, a name, or a constant. 
These statements require labels. 

Note: If you define symbols by EQU statements, you can 
define them only once in the program. If you define symbols 
by SET statements, you can redefine them by subsequent 
SET statements. 

In EQU statements the label name must not have been used 
previously, and the operand cannot include a name that has 
not yet been defined (that is, it cannot contain as-yet unde- 
fined names the definitions of which also use undefined 
names). 

In a good program all equates are at the beginning. This lets 
the assembler generate the most compact code by selecting 
direct addressing wherever possible. 
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You can use EQU to define program symbolic constants, 
especially those used in conjunction with instructions. You 
can use SET to define symbols that control the assembler 
operations, especially conditional assembly and listing con- 
trol. Examples: 



FIVE 


equ 


5 


OFFSET 


equ 


address-base 


TRUE 


equ 


$FF 


FALSE 


equ 





SUBSET 


set 


TRUE 




ifne 


SUBSET 




use 


subset, defs 




else 






use 


full.defs 




ende 




SUBSET 


set 


FALSE 



IFxx <expression> 
<statements> 

[ ELSE ] 

<statements> 

ENDC 



The assembler has conditional assembly capability. Jt can 
selectively assemble or not assemble one or more parts of a 
program, depending on a variable or computed value. There- 
fore, a single source file can selectively generate multiple 
versions of a program. 

Conditional assembly uses statements similar to the branching 
statements in high-level languages such as Pascal and 
BASIC. The generic IF statement is the basis of this capabil- 
ity. Its operand is a symbolic name or an expression. 

The assembler compares the results. If the results are true, the 
assembler processes the statement following the IF statement. 
If the results are false, the assembler does not process the 
statement until it encounters an ENDC (or ELSE) statement. 



98 



Hence, the ENDC statement marks the end of a conditionally 
assembled program section. In the following example the 
IFEQ statement tests for equality of its operand with zero: 

IFEQ SWITCH 

ldd #0 assembled only if SWITCH = 

leax 1 ,x 

ENDC 

The ELSE statement lets the IF statement select one of two 
program sections to assemble, depending on the truth of the 
IF statement. The assembler processes statements following 
the ELSE statement only if the results of the comparison are 
false. For example: 

IFEQ SWITCH 

ldd #0 assembled only if SWITCH = 

leax 1 ,x 

ELSE 

ldd #1 assembled only if SWITCH is not - 

leax — 1 ,x 

ENDC 

You can use multiple IF statements and nest them within 
other IF statements. They cannot, however, have labels. Each 
IF statement performs a different comparison. 

IFEQ True if operand equals zero 

IFNF^ True if operand does not equal zero 

IFLT True if operand is less than zero 

IFLE True if operand is less than or equal to zero 

IFGT True if operand is greater than zero 

IFGE True if operand is greater than or equal to zero 

IFF! True only during Pass 1 (no operand) 

You can use the IF statements that test for less than or greater 
to test the relative value of two symbols if they are subtracted 
in the operand expression. For example, 

IFLE MAX-MIN 

is true if MIN is greater then MAX. 
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NAM string 
TTL string 



Note: The logic is reversed, because this statement literally 
means 

IF MAX-MIN <-= 

The IFP1 statement causes subsequent statements to be pro- 
cessed during Pass 1, but skipped during Pass 2. It is useful 
because it allows program sections that contain only symbolic 
definitions to be processed only once during the assembly. 
Pass 1 is the only pass during which they are actually pro- 
cessed because they do not generate actual object code 
output. 

The OS9Dcfs file is a rather large section of such definitions. 
For example, many source files have the following statement 
at the beginning. 

IFP1 

use /d()/defs/OS9Defs 
EN DC 



define or redefine a program name and listing title line that is 
printed on the first line of each listing page's header. 

These statements cannot have label or comment fields. 

These statements display the program name on the left side of 
the second line of each listing page; a dash and the title line 
follow. You may change the name and title as often as you 
wish. 

Examples: 

nam DATAC 

ttl Data Acquisition System 

Generates: 

Datac - Data Acquisition System 
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OPT <option> 



sets or resets any of several assembler control options. 

The operand of the OPT statement is one of the characters 
that represents the various options. If a minus sign { -) pre- 
cedes the option name, the option is turned off: otherwise, it 
is turned on. Two exceptions are the D and W options, which 
must be followed by a number. This statement must not have 
label or comment fields. 



Option Default (initial) State 



C Conditionals On — displays conditional assembly 

statements in the listing. (C) 

Dnum Page Depth — sets the number of lines per listing 

page, including heading and blank line. (D66) 

E Error Messages On — displays error messages in 

listing. When this option is off, an E appears in 
a statement's informational field if an error is 
present. (E) 

F Use Form Feed — uses a form iced for page eject 

instead of line feeds. ( — F) 

G Generate All Constant Lines — displays all lines 

of code generated by pseudo instructions. Other- 
wise, it displays only the first line. (— G) 

L Listing On — generates formatted assembly list- 

ing. If off, the assembler displays only error mes- 
sages. ( L) 

M Mode On — turns on Motorola-compatible 

mode. ( - M) 

N Narrow Listing — generates listing in a non- 

col umnized, compressed format for better pre- 
sentation on narrow video display devices. ( - N) 

O | - file name | generates object code file: ( O) 
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If you do not specify a file name, the assembler 
creates an object file having the same name as the 
input file in the current execution directory. 

If you specify a single name, the assembler cre- 
ates an object file having that name but still in the 
current execution directory. 

H you specify a full pathlist, the assembler uses it 
as the name specification of the device, directory, 
and file to create. 

S Generate Symbol Table — displays the entire 

contents of the symbol table at the end of the 
assembly. Displays each name, its value, and a 
type code character: 

D = data variable (RMB definitions) 

E - equate label (EQU) 

L = program label 

S = set label 

U = undefined name 

The table is displayed across the page in alpha- 
betical order. ( — S) 

W//w/?7 Set Page Width — defines the maximum length 

of each listing line. Lines are truncated if they 
exceed this number. The comment field starts at 
column 50; therefore, a number smaller than this 
may cause important parts of the listing to be lost. 
(VV80) 

Examples: 

opt 1 

opt w72 
opt s 
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ORG <expression> 



PAG[E] 



changes the value of the assembler's data location counter 
(normal mode) or the instruction location counter (Motorola- 
compatible mode). 

It evaluates the expression and sets the appropriate counter to 
the value of the result. ORG statements cannot have labels, 

Note: OS-9 does not use load records that specify absolute 
addresses of the generated object code. The object code is 
assumed to be a contiguous memory module. Therefore, pro- 
grams assembled using the Motorola-compatible mode that alter 
the instruction address counter do not load correctly. 

Examples: 

ORG DATAMEN 

ORG . + 200 



begins a new page of the listing. The alternate form of PAG is 
PAGE for Motorola compatibility. 



SPC <expression> 



puts blank lines in the listing. 

The value of the operand, which can be an expression, constant, 
or name, determines the number of blank lines to be generated. 
If you use no operand, a single blank line is generated. 

The above two statements improve the readability of program 
listings. They are not themselves displayed and cannot have 
labels. 



SETDP <expression> 



assigns a value to the assembler's internal direct page counter, 
which is used to automatically select direct versus extended 
addressing. 
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USE pathlist 



The direct page counter does not necessarily correspond to the 
program's actual direct page register during execution. The 
default value of the counter is zero and should not be changed in 
OS-9 programs; this statement is intended for use with the 
Motorola-compatible mode only. SETDP statements cannot 
have labels. 



temporarily stops the assembler from reading the current input 
file. It then requests OS-9 to open another file or device speci- 
fied by the pathlist, from which it reads input lines until an 
end-of-file occurs. At that point, the assembler closes the latest 
file and resumes reading the previous file from the statement 
following the USE statement. 

You can nest USE statements (for example, a file being read as 
the result of a USE statement can also perform USE statements) 
up to the number of simultaneously open files the operating 
system allows (usually 13, not including the standard I/O 
paths). Some useful applications of the USE statement are to 
accept interactive input from the keyboard during assembly of a 
disk file (as in USE/TERM) and to include library definitions or 
subroutines into other programs. USE statements cannot have 
labels. 
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7 / DEFS Files: Fact or Fiction 



OS9DEFS 



Most programmers use the OS9Defs file with assembly- 
language programs and add their own definitions to this file. To 
include the OS9Dcfs file with your source code when assemb- 
ling the file, use the following statements: 

IFP1 

USE /D0/DEFS/OS9DEFS 

ENDC 
This speeds up assembly and prevents the OS9Defs file from 
being displayed every time. 

OS9Defs contains the following groups of defined symbols: 

System Service Request Code 

Signal Codes 

Status Codes For Getstat/Putstat 

Direct Page Variables 

Table Size 

Module Format and Offsets 

Module Field Definitions 

Module Type/Language Masks and Definitions 

Process Descriptor 

Process Status Flags 

OS-9 System Entry Vectors 

Path Descriptor Offsets 

File Access Modes 

Pathlist Special Symbols 

File Manager Entry Offsets 

Device Driver Entry Offsets 

Device Table Format 

Device Static Storage Offsets 

Interrupt Polling Table Format 

Register Offsets on Stack 

Condition Code Bits 

System Error Codes 

I/O Error Codes 

This chapter is a reference source, not a guide to the structure 
and workings of the operating system. For more extensive 
information, see OS-9 Technical Information. 
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System Service Request Codes 



Signal Codes 



a group of labels that define all OS-9 system calls and list their 
associated values. These labels let you use the system request 
name in an OS-9 call. 



a group of labels that define the four OS-9 signals and their 
associated values. This is an appropriate place for your own user 
defined signals. 



Status Codes for GetStt and SetStt 



a group of labels that list and give the values for the predefined 
status call functions of the system calls l$GetStt and l$SetStt 
that are supported by OS-9 file managers and device drivers. 
These labels arc then available for loading the B register before 
the call is made. This is an appropriate place for your own user 
defined status codes. 



Direct Page Variables 



Table Size 



a group of labels that define the offsets into page of OS-9 
system variables. OS-9 uses page variables for interrupt vec- 
tors, table addresses, process queues, and internal memory 
information. We strongly recommend that you not use page 
variables in your programs, unless you write special drivers and 
interrupt handlers or debug systems. Using these variables im- 
properly can cause unexpected and perhaps fatal system 
operation. 



a group of equates that define the size of the table that the OS- 
operating system uses internally. 
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Module Format and Offsets 



a group of labels that define the offsets into a module header of 
all OS-9 compatible modules. You can use module offsets to 
find information in a module, for example, the module's size, 
name, type, or language. In this group are the Universal Module 
offsets and the offsets for specific module types. Descriptors, 
drivers, programs, and file managers have a different module 
format. 



Module Field Definitions 

Module Type/Language Masks and Offsets 

Module Attributes/Revision Masks and Offsets 



a group of symbols that define the bits of information that go 
into a module header. You can use this section to decode a 
module header and modify one. Since the OS-9 Interactive 
Assembler generates a module header with the MOD and 
EMOD, use these symbols to read a header. This group defines 
masks according to type, language, attribute, and revision bytes 
and lists the values lor each field. 



Process Descriptor 



contains the table of information describing a process. 



Process Status Flags 



define the flags that OS-9 uses to mark a process for different 
states, for example, dead and sleeping. 



OS-9 System Entry Vectors 



a group of symbols that define OS-9 system entry points. These 
are the vector addresses for the various interrupts. They are 
pseudo vectors, not actual hardware vector points. 
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Path Descriptor Offsets 



File Access Modes 



a group of symbols that define the offsets for OS -9 path descrip- 
tors. OS -9 creates a path descriptor offset for every path opened 
in the system. 



a group of symbols that define the file access modes under 
OS-9. You can use these definitions for I$Create and ISOpen 
system calls that require the file attributes to be set at the time of 
the call. 



Pathlist Special Symbols 



a group of symbols that define the special pathlist characters. 
You can use them to parse a pathlist. This is an appropriate place 
to insert special characters that you use frequently. 



File Manager Entry Offsets 



a group of symbols that define the entry offsets of all file 
managers on an OS-9 system. If you write your own file man- 
ager, you must provide these entry offsets. 



Device Driver Entry Offsets 



a group of symbols that define all entry offsets of device drivers 
in the OS-9 system. You must provide these offsets at the 
beginning of your drivers. 



Device Table Format 



a group of symbols that define the form of the table that contains 
an entry for every active device in the OS-9 system. The 
operating system uses this information internally. 



Device Static Storage Offsets 



a group of symbols that define the variables within a device 
static storage area. This area contains information about the 
device and is filled in when the device is activated. The actual 
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filling in of the parameters is done by three sourecs: IOMAN, 
the file manager, and the device driver. The offsets listed in this 
area are filled in by IOMAN. 



Interrupt Polling Table Format 



a group of symbols that define the structure of the entries for the 
polling table. The format contains all the information the inter- 
rupt service routine needs to handle interrupts generated by 
active devices. OS -9 uses this information internally. 



Register Offsets on Stack 



a group of symbols that define the offset to the registers that are 
pushed on the stack whenever the 6809 CPU gets an interrupt of 
the form NMI, IRQ, SWL SWI2 (an OS-9 system call), or 
SWI3. You can use these symbols when writing drivers to get 
the I$GetStt or I$SetStt codes. You can also use them to pass 
parameters on the stack to different procedures in a program. 



Condition Code Bits 



a group o\' symbols that define the values for each condition 
code. Use these masks to set or reset the bits. It is good 
programming practice to use these labels in your code. 



System Error Codes 
I/O Error Codes 



a group of labels that define all errors returned by OS-9 and the 
I/O handlers. If your programs have any form of error trapping, 
you must compare the error to a known error definition in order 
to determine what should occur. 
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SCFDEFS 



In this tile arc the definitions pertaining to the sequential file 
manager and sequential file deviees. It contains the following 
groups of defined symbols: 

Static Storage Requirements 
Character Definitions 
File Descriptor Offsets 

You can use this file when writing drivers for sequential devices 
and managers. This is an appropriate place for your own SCF 
definitions. For more information on any group of defined 
symbols, see the OS -9 Technical Information. 



Static Storage Requirements 



a group of symbols that define the offsets to the static storage 
required by SCF devices. This area continues from V.USFR 
defined in OS9DFFS. SCF devices must reserve this space for 
the SCF manager. The driver determines the storage reserved 
after this group. 



Character Definitions 



a group of symbols that arc defined so that certain SCF devices 
can filter special characters. This is an appropriate place for 
adding your own SCF special characters. 



File Descriptor Format 



a group of symbols that describe the file manager's parameters. 
The actual total storage is declared in OS9Defs under the entry 
called Path Descriptor Offsets. Both SCF and RBF have their 
own definitions of the PD.FST and PD.OPT fields. This is 
where SCF's definitions are located. 



110 



RBFDEFS 



In this file are the definitions pertaining to random block file 
managers and random file devices, It contains the following 
groups of defined symbols: 

Random Block Path Descriptor Format 

State Flags 

Device Descriptor Format 

File Descriptor Format 

Segment List Kntry Format 

Directory Entry Format 

Static Storage 

You can use this file when writing random block file managers 
and devices. This is the appropriate place for adding your own 
RBF definitions. 



Random Block Path Descriptor Format 



State Flags 



a group of symbols that define the file descriptor offsets for RBF 
devices. The actual total storage is declared in OS9DEFS under 
Path Descriptor Offsets. Both SCF and RBF have their own 
definitions of the PS.FST and PD.OPT fields. This is where 
RBF's definitions are located. 



a group of symbols that define the flags that OS-9 uses internally 
to mark the state of the disk buffer. 



Device Descriptor Format 



a group of symbols that define the format of the contents of 
sector zero of an RBF device. RBF uses this format to find the 
actual physical information on the device. OS -9 uses this in- 
formation to fill in the drive table. This differs from SCF type 
devices in that the actual device information is kept on the 
media. The device descriptor in memory is then mainly used by 
the format program. 
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File Descriptor Format 



a group of symbols that defines a format that is kept on disk and 
contains information on the file, for example, its size, segment 
list, and owner. RBF reads in this information and uses it when 
accessing a file. Whenever you modify the file, this sector is 
modified. 



Segment List Entry Format 



a group of symbols that define an entry in a file segment list. The 
actual list is composed of the beginning sector and the size (in 
number of sectors) of each segment of the file. Files that have 
extensions also have an additional segment for the segment list. 



Directory Entry Format 



Static Storage 



two symbols that define a directory entry, the file name and the 
file descriptor sector address. 



a group of symbols that define the size and format of the drive 
tables allocated by the driver. The drive tables begin at 
DRVBBG and continue to DRVMEM. Also V.NDRV is allo- 
cated before the tables and defines the number of drives and 
therefore the number of tables used by a driver. The rest of the 
static storage is defined in OS9DKFS and in the driver. You can 
use this information when writing your RBF device driver. 
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SYSTYPE 



This file contains descriptions of the physical parameters of the 
various OS-9 systems. Some of those parameters are: 

CPU Type Definitions 
CPU Speed Definitions 
Disk Controller Definitions 
Clock Module Definitions 
PI A Type Definitions 
System Type Definitions 
Disk Port Address 
Disk Definition 
Disk Parameters 
Clock Port 
I/O Port 

You can use this file when writing or modifying drivers. All the 
necessary information is supplied on the file. 
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8 / Assembly-Language 

Programming Techniques 



For your program to run correctly in the OS-9 environment, it 
must be position-independent, and all memory locations mod- 
ified by the program (variables and data structures) must be in 
an area that OS-9 assigns at run time. 

You have no control over which addresses OS-9 assigns at a 
load area or over where OS-9 assigns the program's variables. 
Because of the powerful 6809 instruction set and addressing 
modes, these rules do not force you into writing tricky or 
complex programs; rather, they require you to write programs in 
a specific way. 

Your programs usually fall into one of three categories: 

1. A subroutine or subroutine package. You must 
write your subroutines in position independent 
code. Data sections are usually a matter of coor- 
dination with the calling program, and OS-9 nor- 
mally plays no direct role in this. 

2. A program to be executed as an individual process 
(commands are of this type). You must use position 
independent code and receive data area parameters 
that delineate the assigned memory space. 

3. Programs to be run on another, non-OS-9 
computer. 



Program Sections and Data Sections 



If you run your program as a process (by means of the OS-9 
Shell, fork system call, or execute system call), OS-9 assigns 
two separate and distinct memory areas. The program object 
code loads into one memory space in the form of a memory 
module. Variables and data structures load into the other space. 
The program's module header specifies the minimum permissi- 
ble size for each area. 
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The distinction between these two spaces is extremely impor- 
tant. The data address counter Ls for the data area, and the 
instruction address counter is for the program area. The values 
of both counters are never absolute addresses. They are relative 
to the beginning of an OS-9-assigncd address. 



Program Area 



The program area is a simple, continuously allocated memory 
space where OS-9 loads the program. For OS-9 to load the 
program, it must be in memory module format. OS-9 Technical 
Information contains a detailed description of memory modules 
and how they work. This manual assumes you are familiar with 
them. 

The assembler generates programs that can consist of one or 
more memory modules. It writes them to the same file, and 
OS-9 loads them together. In assembly-language source pro- 
grams, modules usually begin with a MOD pseudo-instruction 
and end with an KMOD pseudo-instruction. These take care of 
the header and module CRC generation for you. 

Never modify the program area by the program itself, especially 
if the program is to be reentrant and/or placed in ROM. It can 
(and should) contain constants and constant tables, as long as 
they are not altered by the program. 



Position Independent Mode 



You do not know the absolute address of anything in the pro- 
gram until it is run. The 6809 position-independent addressing 
modes are based on "program counter relative addressing/' All 
branch and long-branch instructions use this addressing mode. 

- > Use BRA and LBRA instead of JMP; use BSR and LBSR 

instead of JSR extended or direct mode instructions (indexed is 
OK). 
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All load, store, arithmetic, and logical instructions can use the 
program-counter-relative (PCR) indexed addressing mode. 
- > Do not use immediate addressing to load a register with 
an absolute address (instruction label name). Use PCR indexed 
addressing instead. 

Many well-written programs use constant tables of addresses 
(often called dispatch tables or pointer tables). For the program 
to be position independent, these tables cannot contain absolute 
addresses. You must create tables of addresses that are relative 
to an arbitrary location. The routines that use the tables read the 
table entries and then add them to the absolute address of the 
arbitrary location. The sum is the run-time absolute address. 

You can determine the absolute address of the arbitrary location 
by using PCR instructions (typically LHA). The choice of the 
common address is arbitrary, but two places may have specific 
advantages: the beginning address of the table (an index register 
probably will contain this address anyway); and the first byte of 
the module. 

Making table entries relative to the start of the module is 
especially handy because the value of the assembler's instruc- 
tion address counter is also relative to the beginning address of 
the module. 

In the following example, a routine jumps to one of several 
subroutines, the relative addresses of which are contained in a 
table. The instructions pass the routine to a number in the B 
accumulator, which uses it as an index to select the routine. 

begin mod a,b.e.d,e,f start of module 

(various instructions) 

dispat leax table. per get the absolute 

address of the table 
aslb multiply index by 2 

(two bytes/entry) 
Idd b.x get contents of table 

entry 
leax beg in. per get beginning 

address of module 
jmp d,x add relative address 

and go... 
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tabic Mb routine 1 

fdb routinc2 

fdb routined 

fdb routine4 

In the following example the entries are relative to the beginning 
of the table instead o( to the beginning of the module. 

dispat 



leax 


table, per 


get the absolute 
address of the table 


aslb 




multiply index by 2 


ldd 


b,x 


get routine offset 


jmp 


d,x 


add and go... 


fdb 




routine 1 -table 


fdb 




routine2-table 


fdb 




routine3-table 


fdb 




routine4-table 



table 



The above example contains fewer instructions. It is also faster 
because the register already contained the reference address in a 
register; therefore, you can eliminate a LEAX instruction. This 
technique is also useful for accessing character strings, con- 
stants, complex data types, and so on. 



Accessing the Data Area 



The "minimum permanent storage size 1 ' entry of the module 
header specifies the size of the data area. A program may, 
however, occupy more than this minimum. OS-9 allocates 
memory in multiples of 256-byte pages, and it allocates all 
processes at least one page. The data area must be large enough 
for all the program's variables and data structures, plus a stack 
(at least 250 bytes) and space to receive parameters. 

When OS-9 calls the process, it passes the bounds of the data 
area to the process in the Registers MPU. U contains the 
beginning address, and Y contains the ending address. It sets the 
Register SP to the ending address + 1, unless parameters were 
passed. It sets the direct page register to the page number of the 
beginning page. 
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In the assembly-language source program, you can assign stor- 
age in the data area with the RMB pseudo instruction, which 
uses the separate data address counter. You need to declare all 
variables and structures at the beginning of the program. De- 
clare smaller, frequently used variables first. They usually fit in 
the first page, and you can access them with short, fast direct- 
page addressing instructions. Follow with larger items. You can 
address them in two ways: 

1 . If you maintain a Register throughout the program, 
use constant-offset-indexed addressing. 

2. Part of the program's initialization routine can com- 
putc the actual addresses of the data structures and 
store them in pointer locations in the direct page. 
Obtain the addresses later with direct-page addres- 
sing mode instructions. 

Note: You cannot use program-counter relative addressing to 
obtain addresses of objects in the data section, because the 
memory addresses assigned to the program section and the 
address section are not a fixed distance apart. Of course, im- 
mediate and extended addressing are not generally usable. 

The following example illustrates the U relative technique. 

* declare variables 



tempi 


rmb 2 


temp2 


rmb 2 


bufl 


rmb 400 


buf2 


rmb 400 


buf3 


rmb 400 
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* clear each 400-byte buiTer 

leax but 1 ,u get address of buf I 

bsr clrbuf 

leax buf2,u get address of buf2 

bsr clrbuf 

leax buf3,u get address of buO 

bsr clrbuf 

* clear buffer subroutine 

* X = address of buffer 



clrbuf 


Idd #400 


D = byte count 


cloop 


clr ,x + 


clear byte and advance pointer 




subd # 1 


decrement count 




bne cloop 


loop if not done yet 




rts 
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9 / Assembler Error Reporting 



When the assembler deteets an error, it displays an error mes- 
sage just before the line containing the error. If a statement has 
two or more errors, the assembler displays each error on a 
different line preceding the erroneous line. 

If the -L option inhibits the assembler, the assembler still 
displays error messages and erroneous lines. The statistical 
summary displayed at the end of the assembly contains the total 
numbers of errors and warnings. The assembler writes the error 
messages, erroneous source lines, and the assembly summary to 
the assembler task's error and status path, which the shell may 
redirect. The assembler writes the listing to the output path, 
which it may redirect independently of the error messages. This 
is useful when a procedure file calls the assembler. Hxamplc: 

asm sourcefile — I >same. listing >>save.errs 

You can perform a quick assembly just to check for errors by 
calling the assembler with the listing and object code generation 
both disabled by the - L — O options. In this way you can find 
and correct many errors before displaying a lengthy list. 
Example: 

asm sourcefile - I -0 

The — H option turns off error-message display, but you can still 
detect lines containing errors by the presence of an H in the 
informational column of the listing line. You may want to use 
this option to generate a fc 'cleaner' ' listing of a program known 
to have many errors. 

Sometimes the assembler stops processing an erroneous line, 
and therefore you may not be able to detect additional errors on 
the same line; so make corrections carefully. 



Explanation of Error Messages 

Error messages consist of brief phrases that describe the error. 
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Syntax and Grammar Errors 



Improperly constructing source statements can cause the fol- 
lowing errors of syntax and grammar. 

ADDRESS MODE. The addressing mode specified is not 
legal for the instruction. 

BAD INSTR. The assembler does not recognize the in- 
struction given in the source statement. 

BAD LABEL. The statement's label contains an illegal 
character or does not begin with an alphabetical character. 

] MISSING. A closing bracket is missing. 

CONST DEF. The instruction requires a constant or an 
expression that is missing or in error. 

INDEX REG. The instruction requires the name of an 
index register but none was found. 

LABEL NOT ALLOWED. This type of statement cannot 
have a label. 

NEEDS LABEL. The statement must have a label. 

OUT OF RANGE. The destination (label) of the branch is 
too far to use a short-branch instruction. 

REG NAM. The required register name is missing or 
misspelled. 

REG SIZES. The registers specified in a TFR or EXG 
instruction are of different lengths. 



Arithmetic Errors 



Improper arithmetic or the use of improper arithmetic expres- 
sions can result in the following errors. 

DIV BY 0. A division with a zero divisor occurred. 
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EXPR SYNTAX. The arithmetic instruction is illegally 
constructed or is missing an operand following an 
operator. 

IN NUMBER. A constant number (decimal, hexa- 
decimal, or binary) is too large or contains an illegal 
character. 

MULT OVERFL. The result of a multiplication is more 
than 65,535 (two bytes). 

PARENS. The expression contains an unequal number of 
right and left parentheses. 

RESULT>255. The result of the expression is too large 
to fit in the 1 -byte value used by the instruction. 



Symbolic Name Errors 



When symbolic names are improperly used, defined, or rede- 
fined, the following errors can occur. 

PHASING. The statement's label had a different address 
during the first assembly pass. This usually happens when 
an instruction changes addressing modes, and thus its 
length, after the first pass because its operand becomes 
defined after the source line is processed. Usually the 
error occurs on all labels following the offending source 
line. 

REDEFINED NAME. The label was defined previously 
in the program. 

UNDEFINED NAME. The symbolic name was never 
defined in the program. 
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Assembler Operational Errors 



Using the assembler incorrectly can cause the following errors. 

CAN'T OPEN PATH. The file cannot be opened (source 
file) or created (object file). 

INPUT PATH. The input path contains a read error. 

MHMORY FULL. The symbol table is full. More mem- 
ory is required to assemble the program. 

OBJECT PATH. The object file contains a write error. 

OPT LIST. The assembler command line or an OPT 
statement contains an illegal option or is missing an 
option. 
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Appendix A / Sample Command 

Lines 



asm disk— crash 



assembles the file disk_crash. 

This command does not create a listing or an object file. It 
reports error to the standard error path and establishes 4K 
memory for symbols (asm default). 



asm work.rec o #16k 



assembles the file work.rec. 

This command does not create a listing. It does create an object 
tile with the name work.rec in the current commands directory. 
It reports errors to the standard output path and establishes 16K 
memory lor symbols. 



asm tyco = /dO/cmds/tyco.obj 1 #16k 



assembles the file tyco. 

This command creates a listing directed at the standard output 
and an object file with the name tyco in the /dO/cmds directory. 
It reports errors to the listing path and establishes 16K memory 
for symbols. 



asm iL-works o,l #16k >/p 



assembles the file it_works. 

This command creates a listing directed at /p and an object file 

with the name it— works in the current commands directory. It 

reports errors to the listing path and establishes 1 6K memory for 

symbols. 



asm test_util I,s,w72,d25 #10k 



assembles the file test util . 

This command creates a listing directed at the standard output. 
The listing has 25-line pages and 72-column lines. It does not 
create an object file. It establishes 1 OK memory for symbols and 
creates a symbol table. It reports errors to the listing path. 
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asm /term i 1 o = dO/progs/woof 



assembles input from the terminal. 

This command creates a listing directed at the standard output 
and an object file with the name woof in the /d() progs directory. 
It reports errors to the listing path and establishes 4K memory 
for symbols (asm default). 
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Appendix B / Error Messages 

Abridged 



The assembler displays an error message for each error it de- 
tects. It displays the messages before the line in which the error 
occurs . You can suppress the display of error messages by using 
the — E command. 

ADDRESS MODE. The specified addressing mode is not 
legal for the instruction. 

BAD INSTR. The assembler does not recognize the in- 
struction given in the source statement. 

BAD LABEL. The statement's label contains an illegal 
character or docs not begin with a letter. 

] MISSING. A closing bracket is missing. 

CAN'T OPEN PATH. The file cannot be opened. 

CONST DEF. A constant expression is missing or in 
error. 

DIV BY 0. A division with a zero divisor occurred. 

EXPR SYNTAX. The arithmetic instruction is illegally 
constructed or is missing an operand following an 
operator. 

INDEX REG. The name of an index register is required 
but none was found. 

IN NUMBER. A constant number (decimal, hexa- 
decimal, or binary) is too large or contains an illegal 
character. 

INPUT PATH. The input path contains a read error. 

LABEL NOT ALLOWED. The statement cannot have a 
label. 

MEMORY FULL, The symbol table is full; create more 
memory to assemble the program. 

MULT OVERFL. The result of a multiplication is more 
than 65,535. 

NEEDS LABEL. The statement requires a label. 
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OBJHCT PATH. The object file path contains a write 
error. 

OPT LIST. An option is illegal or missing. 

OUT OF RANGE. The destination of the branch is too far 
to use a short-branch instruction. 

PARENS. The expression contains an unequal number of 
right and left parentheses. 

PHASING. The value of the instruction address or data 
address counter was different during Pass I; that is, an 
instruction changed addressing modes and length during 
Pass 2. 

REDEFINED NAME. The label was defined previously 
in the program. 

REG NAM. A register name is missing or misspelled. 

RF]G SIZES. The registers specified in a TFR or EXG 
instruction are of different sizes. 

RESULT>255. The result of the expression is too large 
to fit in the required byte. 
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Appendix C / Assembly Language 

Programming 
Examples 



The following pages contain three assembly language program- 
ming examples. They are: 

UpDn -Program to convert input case to upper or 

lower. 
P -Parallel interface descriptor. 

These programs are provided to give an example of what an 
assembly language program should be in the way of structure 
and form. They also provide the programmer with a guide to 
three of the main program types. 
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UPDN 



UpDn — Assembly Language 
Programming Example 



* this is a program to convert characters from 

* lower to upper case (by u s i n d the u option) 

* the method of passing the paramters through 

* o s 3 is used here (system calls) 

* to use type 

* "up dm u(oPt for lower to upper) < 'input' > 'output'" 
* 

i"i am U p D n 

* file include in assewbl v 

if pi 

use /D0/defs/os9defs 
e n d c 
* 

* S - 9 System Definition File Included 
# 

apt 1 

1 1 1 Assembly L a n 3 u a 3 e E x a m p 1 e 
* 

* Module header macro 
* 

0000 87CD005D mod UDS I Z tUDNAM ,TYPE tREVS t ST ART t S I ZE 

000D 757064EE UDNAM fcs /updn/ module name for memory 
0011 TYPE set PRGRM+OBJCT mod type 

008 1 REMS set REENT+1 mod revision 

* 

* storage area for variables 
* 

D0000 TEMP rmb 1 temp storage for read 

D 0001 UPRBND rmb 1 storage for upperbound 

D 0002 LWRBND rmb 1 storage for lowerbound 

D 0003 rmb 250 storage for stack 

D00FD rmb 200 storage for parameters 

D 01C5 SIZE e^u ♦ en d o f d a t a a re a 

# 

* actual code starts here 

* x register is pointing to start of parameter area 

* y register is pointing to end of parameter area 

* this is how to set a parameter that is passed on 

* the command line and where to 1 o o K for it 



130 



0011 
0011 



AS80 



START 
SRCH 



e r u 
Ida 



start of executable 
search parameter area 



0013 84 DF anda fltdf 

00158155 c m p a # ' U 

0017 270E bei UPPER 

0019810D ciripa *$0d 

001B 2GF4 bne SRCH 

* 

* fall through to set upper to lower bounds 



m a K e upper case 
see if a U was input 
branch to set uppercase 
see if a carriage return 
#o set another char 



001D 8641 Ida # 'A 

001F 9702 sta LWRBND 

0021 8G5A Ida #'2 

0023 9701 sta UPRBND 

0025 2008 bra START1 

# 

* set lower to upper bounds 



set lower b o u n d 

set it in storage area 

Set upper bo u n d 

set it in storage area 

So to start of code 



0027 
0029 
002B 
002D 



8BB1 
9702 
8G7A 
9701 



UPPER Ida #'a 

sta LWRBND 

Ida # ' z 

sta UPRBND 



set lower b o u n d 

set it in storage 

Set upper bou n d 

set it in storage 



* c o n i; e r t i n g c o d e 

* this part uses the I $ R E A D and 

* the I$WRIT system calls 

* read the systems programmers ma 

* for information relating to t 
002F 30C4 START1 leax teirsp.u 
0031 8G00 Ida #0 

0033 108E0001 Idy ##01 

0037 103F89 LOOP os9 I$READ 

003A 2515 be s EXIT 

003C D600 ldb TEMP 

003E D102 empb WRBND 

0040 250B bio WRITE 

0042 D101 empb UPRBND 

0044 2202 bhi WRITE 

0046 C820 eorb #$20 

0048 D700 WRITE stb TEMP 

004A 4C inca 

004B 103F8A os9 I$WRITE 

004E 4A deca 

004F 24ES bec LOOP 

0051 C1D3 EXIT empb #E$EOF 

0053 2601 bne EXIT1 

0055 5F cl rb 

005G 103F0G EXIT1 os9 F*EXIT 

0059 2G04D9 emod 

005C UDSIZ e^u * 

END 



n u a 1 

h em 

Set s 
stan d 
n u m b e 
do th 
exit 
$9 t c 
test 
bra n c 
test 
bra n c 
flip 
put 1 
re S ' 
write 
retur 
Set c 
is it 
not e 
clear 
error 
last 
size 



t o ra 
ard 
r of 
e re 
if e 
h a r a 
char 
h if 
char 
h if 
case 
t n-) 
a ' s 

the 
n to 
ha r 

an 
of t 

car 

ret 
co mm 
of p 



3 e address 
i n p u t 

characters 
ad 

r r o r 
cter read 

bound 

o ut 

b o u n d 

Lit 

b i t 

s t o ra Se 
t a n d outp u t 

character 

stand i n p u t 
if no error 
EOF error 
1 e a u e carry 
r / f no error 
urnedf exit 
a n d 
r o s r a m 
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Device Descriptor for 



if Pi 
e n d c 

ttl Deuice Descriptor for "P" 
**************** 

PRINTER device module 



0000 87CD0035 

000D 02 

000E FF 

000F E040 

0011 18 

0012 00 



mod PRTEND ,PRTNAM »DEUIC+0B JCT * 

REENT+1 *PRTMGR ,PRTDRY 

fob WRITE mode 

fcb $FF 

fcb A * P port address 

fcb PRTNAM-*-loption byte count 

fcb DT.SCF Deuice Type: SCF 



* Default Path options 



0013 


00 


0014 


00 


0015 


01 


001S 


00 


0017 


01 


0018 


00 


0019 


00 


001A 


42 


0015 


08 


001C 


18 


001D 


0D 


001E 


00 


001F 


04 


0020 


01 


0021 


17 


0022 


00 


0023 


00 


002a 


5F 


0025 


07 


002B 


01 


0027 


00 



fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 






1 



1 




G6 

C$BSP 
C$DEL 
C$CR 



C$RFRT 
C$RPET 
C$PAUS 





C#BELL 
PIASID 



ase^UP 
a c K s p a 
elete= 
o auto 
uto 1 1 
a n u 1 1 
o pa #e 
i n e s p 
a c K s p a 
e 1 e t e 
nd of 
c e n d 
e p r i n t 
up las 
ause c 
o a b a r 
o inte 
a c K s p a 
ine o i j 
rinter 
n d e f i n 



PER 
c e = 
CRL 

e c 
n e 
s a 

pa 
e r 
c e 
lin 
re c 
of 

1 i 
t 1 
h a r 
t c 
r ru 
c e 
e rf 

Jy 
ed 



a n d lower 
B S char only 
F 

ho 

f e e ij on 
fter CR 
us e 
pa 3e 
char 
e char 
o r d char 
file char 
rie char 
i n e char 

haracter 

pt character 

echo char 

low char 

pe 

baud rate 
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0028 0000 

002A D0 
0tf2B BO 
002C 5348CG 
002F 5®asc 



fob 

PRTNAM fcs "P M 

fcs " " 

PRTMGR fcs "SCF" 

PRTDRM fcs "PI A" 



no echo device 

device n a m e 

r o o m for name patching 

file manager 

driver 



0032 A9B118 
0035 



e m o d 



PRTEND EQU 
END 
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Appendix D / 6809 Instructions And 

Addressing Modes 





DIRECT 


EXTEND 


INDEX 


IMMED ACCUM 


INHER 


RELAT REGIS 


ABX 










X 




ADCA 


X 


X 


X 


X 






ADCB 


X 


X 


X 


X 






ADDA 


X 


X 


X 


X 






ADDB 


X 


X 


X 


X 






ADDD 


X 


X 


X 


X 






ANDA 


X 


X 


X 


X 






ANDB 


X 


X 


X 


X 






ANDCC 








X 






ASL 


X 


X 


X 








ASLA 










X 




ASLB 










X 




ASR 


X 


X 


X 








ASRA 










X 




ASRB 










X 




(L)BCC 












X 


(L)BCS 












X 


(L)BEQ 












X 


(L)BGH 












X 


(L)BGT 












X 


(L)BGI 












X 


(L)BHS 












X 


BIT A 


X 


X 


X 


X 






BITB 


X 


X 


X 


X 






(L)BLE 












X 


(L)BLO 












X 


(L)BLS 












X 


(L)BLT 












X 


(L)BMI 












X 


(L)BNE 












X 


(L)BPL 












X 


(L)BRA 












X 


(L)BRN 












X 


(L)BSR 












X 


(L)BVC 












X 


(L)BVS 












X 


CLR 


X 


X 


X 


X 






CMPA 


X 


X 


X 


X 






CMPB 


X 


X 


X 


X 






CMPD 


X 


X 


X 


X 






CMPS 


X 


X 


X 


X 






CMPU 


X 


X 


X 


X 






CMPX 


X 


X 


X 


X 






CMPY 


X 


X 


X 


X 






COM 


X 


X 


X 


X 






CWAI 








X 






DAA 










X 




DEC 


X 


X 


X 


X X 






EORA 


X 


X 


X 


X 






EORB 


X 


X 


X 


X 
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DIRECT EXTEND INDEX IMMED ACCUM INHER RELAT REGIS 



EXG 














INC 


X 


X 


X 




X 




•IMP 


X 


X 


X 








JSR 


X 


X 


X 








LDA 


X 


X 


X 


X 






LDB 


X 


X 


X 


X 






LDD 


X 


X 


X 


X 






LDS 


X 


X 


X 


X 






LDU 


X 


X 


X 


X 






LDX 


X 


X 


X 


X 






LOY 


X 


X 


X 


X 






EEAS 






X 








LEAD 






X 








LEAX 






X 








LEAY 






X 








LSL 


X 


X 


X 




X 




LSR 


X 


X 


X 




X 




MUE 












X 


NEG 


X 


X 


X 




X 




NOP 












X 


ORA 


X 


X 


X 


X 






ORB 


X 


X 


X 


X 






ORCC 








X 






PSHS 














PSHU 














PUES 














PULU 














ROL 


X 


X 


X 




X 




ROR 


X 


X 


X 




X 




RTI 












X 


RTS 












X 


SBCA 


X 


X 


X 


X 






SBCB 


X 


X 


X 


X 






SEX 












X 


STA 


X 


X 


X 








STB 


X 


X 


X 








STS 


X 


X 


X 








STU 


X 


X 


X 








STX 


X 


X 


X 








STY 


X 


X 


X 








SUB A 


X 


X 


X 


X 






SUBB 


X 


X 


X 


X 






SUB 


X 


X 


X 


X 






SWI 












X 


SWI2 












X 


SWI3 












X 


SYNC 












X 


TFR 














TST 


X 


X 


X 




X 
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Appendix E / ASCII Character Set 



SYMBOL 


HEX 


SYMBOL 


HEX 


SYMBOL 


HEX 




VALUE 




VALUE 




VALUE 


NUL 


00 


+ 


2B 


V 


56 


SOH 


01 


' 


2C 


w 


57 


STX 


02 


- 


2D 


X 


58 


ETX 


03 




2E 


Y 


59 


EOT 


04 


I 


2F 


Z 


5A 


ENQ 


05 





30 


L 


5B 


ACK 


06 


1 


31 


\ 


5C 


BEL 


07 


2 


3 


1 


5D 


BS 


08 


3 


33 


a 


5F 


HT 


09 


4 


34 


_„ 


5F 


LF 


0A 


5 


35 




60 


VT 


OB 


6 


36 


a 


61 


FF 


OC 


7 


37 


b 


62 


CR 


OD 


8 


38 


c 


63 


SO 


OE 


9 


39 


d 


64 


SI 


OF 




3A 


c 


65 


DLE 


10 


i 


3B 


f 


66 


DC(XON) 


11 


< 


3C 


g 


67 


DC2 


12 


= 


3D 


h 


68 


DC3CXOFF) 


13 


> 


3E 


i 


69 


DC4 


14 


7 


3F 


j 


6A 


NAK 


15 


(a 


40 


k 


6B 


SYN 


16 


A 


41 


1 


6C 


ETB 


17 


B 


42 


m 


6D 


CAN 


18 


C 


43 


n 


6E 


EM 


19 


D 


44 





6F 


SUB 


1A 


E 


45 


P 


70 


ESC 


IB 


F 


46 


q 


71 


FS 


1C 


G 


47 


r 


72 


GS 


ID 


H 


48 


s 


73 


RS 


IE 


I 


49 


t 


74 


US 


IF 


J 


4A 


u 


75 


SP 


20 


K 


4B 


V 


76 


j 


21 


L 


4C 


w 


77 


" 


22 


M 


4D 


X 


78 


# 


23 


N 


4E 


y 


79 


$ 


24 


O 


4F 


z 


7A 


% 


25 


P 


50 


i 


7B 
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SYMBOL 


HEX 


SYMBOL 


HEX 


SYMBOL 


HEX 




VALUE 




VALUE 




VALUE 


& 


26 


Q 


51 


| 


1Q 




27 


R 


52 


} 


ID 


( 


28 


S 


53 


~ 


IE 


) 


29 


T 


54 


DHL 


7F 


* 


30 


U 


55 
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OS-9 Interactive Debugger 



1 / Introduction 



DEBUG is an interactive debugger that aids in diagnosing 
systems and testing 6809 machine-language programs. You can 
also use it to gain direct access to the computer's memory. 
DEBUG 1 s calculator mode can simplify address computation, 
radix conversion, and other mathematical problems. 



Calling DEBUG 



DEBUG is supplied on your OS-9 system disk . When the screen 
shows the OS-9 prompt, call DEBUG by typing: 



DEDUG CENTER) 

Basic Concepts 



DEBUG responds to 1-line commands entered from the 
keyboard. The screen shows the DB: prompt when DEBUG 
expects a command. 



Terminate each line by typing CENTER) . Correct a typing error by 
using the backspace (left arrow) key, or delete the entire line by 
typing QD while pressing (CLEAR) . 

Each command starts with a single character, which may be 
followed by text or by one or two arithmetic expressions, 
depending on the command. You may use upper- or lower-case 
letters or a mixture. When you use the (SPACEBAR] to insert a 
space before a specific expression, the screen shows the results 
in hexadecimal and decimal notation. Example: 

In the calculator mode, obtain hexadecimal and decimal nota- 
tion for the hexadecimal expression A + 2: 

You Type: (SPACEBAR] QDGD® 

Screen Shows: DB: A + 2 

$000C «00012 
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Note: In the examples in this manual, general instructions are 
followed by specific typing instructions and then by what the 
screen shows. In some cases, examples will follow the explana- 
tion of more than one command. Be sure to execute these 
examples in the exact order in which they are given so that you 
will obtain the specified display on your screen. 
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2 / Expressions 



DEBUG's integral expression interpreter lets you type simple or 
complex expressions wherever a command calls for an input 
value. DEBUG expressions are similar to those used with high- 
level languages such as BASIC, except that some extra oper- 
ators and operands are unique to DEBUG. 

Numbers in expressions are 16-bit unsigned integers, which are 
the 6809's ' 'native 1 ' arithmetic representation. The allowable 
range of numbers is to 65535. Two's complement addition and 
subtraction is performed correctly, but will print out as large 
positive numbers in decimal form. 

Some commands require byte values, and the screen shows an 
error message if the result of an expression is too large to be 
stored in a byte, that is. if the result is greater than 255. Some 
operands, such as individual memory locations and some regis- 
ters, are only one byte long, and they are automatically con- 
verted to 16-bit "words' ' without sign extension. 

Spaces, other than a space at the beginning of a command, do 
not affect evaluation; use them as necessary between operators 
and operands to improve readability. 



Constants 



Constants can be in base 2 (binary), base 10 (decimal), or base 
16 (hexadecimal). Binary constants require the prefix v /v\ deci- 
mal constants require the prefix #. All other numbers are 
assumed to be hexadecimal and may have the prefix S. Exam- 
ples: 



Decimal 


Hexadecimal 


Binary 


#100 


64 


7r 11001 10 


#255 


FF 


f /r 1 1 1 1 1 1 1 1 


#6000 


1770 


7101 1101110000 


#65535 


FFFF 


c /f 1 1 1 1 1 1 1 1 1 1 I 1 1 1 1 1 
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You may also use character constants. Use a single quote (') for 
1 -character constants and a double quote (") for 2- character 
constants. These produce the numerical value of the ASCII 
codes for the characters ) that follow. Examples: 



'A 


= $0041 


'0 


- $0030 


"AB 


= $4142 


"99 


= $3939 



Special Names 



Dot (.) is DEBUG's current working address in memory. You 
can examine it, change it, update it, use it in expressions, and 
recall it. Dot eliminates a tremendous amount of memory 
address typing. 

Dot-Dot (..) is the value of Dot before the last time it was 
changed. Use Dot-Dot to restore Dot from an incorrect value or 
use it as a second memory address. 



Register Names 



Specify Registers MPU with a colon (:) followed by the mne- 
monic name oi the register. Examples: 



A 


Accumulator A 


B 


Accumulator B 


D 


Accumulator D 


X 


X Register 


Y 


Y Register 


U 


U Register 


DP 


Direct Page Register 


SP 


Stack Pointer 


PC 


Program Counter 


CC 


Condition Codes Register 



144 



The values returned are the test program's registers, which are 
4 'stacked' 1 when DEBUG is activve. One-byte registers are 
promoted to a word when used in expressions. 

Note: When a breakpoint interrupts a program, the Register SP 
points at the bottom of the Register MPU stack. 



Operators 



"Operators" specify arithmetic or logical operations to be per- 
formed within an expression. DEBUG executes operators in the 
following order: ( 1) — , negative numbers; (2) & and !, logical 
AND and OR; (3) * and /, multiplication and division; (4) + 
and — , addition and subtraction. Operators in a single express- 
ion having equal precedence, for example, + and — , are 
evaluated left to right. You can use parentheses, however, to 
override precedence. 



Forming Expressions 



An expression is composed of any combination of constants, 
register names, special names, and operators. The following are 
valid expressions: 

#1024 + #128 

:X-:Y-2 

.+20 

:Y*(:X + :A) 

:U & FFFE 
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Indirect Addressing 



Indirect addressing returns the data at the memory address using 
a value (expression, constant, special name, and so on) as the 
memory address. The two DEBUG indirect addressing modes 
are: 

<expression> 

returns the value of a memory byte using expression as an 
address. 

[expression] 

returns the value of a 16-bit word using expression as an 
address. 

Examples: 

<200> 
returns the value of the byte at Address 200. 

[:X] 
returns the value of the word pointed to by Register X. 

[■+10] 

returns the value of the word at Address Dot plus 10. 
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3 / Debug Commands 



Calculator Commands 



CSPACE BMlX expres sion > CENTER] 

evaluates the expression and displays the results in both hexa- 
decimal and decimal. Examples: 



You Type: [SPACEBARS 00 + 2 00 (ENTER) 
Screen Shows: DB: 5000 + 200 

$5200 #20992 



You Type: (SPACEBAR) 8800/2 dNTH 
Screen Shows: DB: 8800/2 

$4400 #17408 



You Type: [SPACEBAR] # 1 + # 1 2 CENTER] 
Screen Shows: DB : #100+#12 

$0070 #00112 

These commands also convert values from one representation to 
another. Examples; 

Convert a binary expression to hexadecimal and decimal: 
You Type: (SPACEBAR) '/, 1 1 1 10000 (ENTER] 
Screen Shows: DB : '£11110000 

$00F0 #00240 

Convert a 1 -character constant to hexadecimal ASCII and dec- 
imal ASCII: 



You Type: (SPACEBAR) ' A (INTER) 
Screen Shows: DB : 'A 

$0041 #00085 

Convert a decimal expression to hexadecimal and decimal: 
You Type: (SPACEBARS 1 00 (ENTER) 
Screen Shows: DB: #100 

$0084 #00100 

You can also use indirect addressing to look at memory without 
changing Dot. Example: 

You Type: (SPACEBAR) ♦ (ENTER) 

Screen Shows: DB : ♦ 

$004F #00079 
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In addition, you can use indirect addressing to simulate 6809 
indexed or indexed indirect instructions. The following exam- 
ple is the same as the assembly language syntax [D,Y], 

You Type: CSPACEBAR) C r D+ : Y ] (ENTER] 

Screen Shows: DB : [ : D+ : Y ] 

$01 10 *00272 



Dot and Memory Examine and Change 
Commands 



displays the current value of Dot (the current working memory 
address) and its contents. Example: 



You Type: * (ENTER) 
Screen Shows: DB : ♦ 

2201 B0 

The present value of Dot is 2201, and BO is the contents of 
memory location 2201. 



increments Dot and displays its new value and contents. 
Example: 

4 'Step through' ' sequential memory locations: 



You Type: dSUR) 
Screen Shows: DB : 

2202 05 
You Type: (ENTER] 

Screen Shows: DB : 

2203 C2 



You Type: (ENTER) 
Screen Shows: DB : 

2204 e: 
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backs up Dot one address and displays its value and contents. 
Example: 

Display the current value of Dot: 



You Type: ♦ CENT1B) 
Screen Shows: DB: . 

2204 82 

Back up one address and display its value and contents: 
You Type: - ( ENTER ) 
Screen Shows: DB : - 

2203 C2 

Back up another address and display its value and contents: 
You Type: - (ENTER) 
Screen Shows: DB : - 

2202 05 



. expression 

changes the value of Dot. This command evaluates the specified 
expression, which becomes the new value for Dot. Example: 



You Type: ♦ 5 00 (ENTER) 
Screen Shows: DB : ♦ 500 

0500 12 



restores the last value of Dot. Example: 

Display the current value of Dot and its contents: 
You Type: ♦ (ENTER) 
Screen Shows: DB : + 

1000 23 

Change the value of Dot: 

You Type: .2000 (ENTER) 
Screen Shows: DB s • 2 000 

2000 9C 
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Restore the last value of Dot: 



You Type: * , dNTEg) 
Screen Shows: DB : • ♦ (ENTER) 
1000 23 



= expression 

changes the eontents o\' Dot. This command evaluates the ex- 
pression and stores the results at Dot. It then increments Dot and 
displays the next address and contents. 

This command also checks Dot after the new value is stored to 
make sure it changed to the correct value. If it did not, the screen 
shows an error message. This happens when you attempt to alter 
non-RAM memory. In particular, the registers of many 6800- 
famiiy interface devices (such as PI As and ACIAs) do not read 
the same as when written to. 
Example: 

Display the current value of Dot and its contents: 
You Type: ♦ (BQBD 
Screen Shows: DB : ♦ 

2203 C2 

Change the contents of Dot: 



You Type: =FF (ENTlR) 
Screen Shows: DB s =FF 

2204 01 

Show that the eontents of Dot have changed: 
You Type: - ISlER) 
Screen Shows: DB z - 

2203 FF 

Warning: This command can change any memory location. 
You can destroy DEBUG, the program under test, or OS-9 if 
you incorrectly change any of their memory areas. 
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Register Examine and Change Commands 



You can use any of several forms of the colon (:) register 
command to examine one or all registers or to change a specific 
register's contents. 

The ''registers'' affected by these commands are actually "im- 
ages" of the register values of the program under test, which are 
stored on a stack when the program is not running. Although a 
"dummy" stack is established automatically when you start 
DEBUG, use the E command to give the register images valid 
data before using the G command to run the program. The 
"registers" are valid after breakpoints are encountered and are 
passed back to the program upon the next G command. 

Note: 

1 . If you change the Register SP, you move your stack 
and the other register contents change. 

2. Bit 7 of Register CC (the E flag) must always be set 
for the G command to work, If it is not set, DEBUG 
does not return to the program correctly. 

: register 

displays the contents of a specific register. The contents are in 
hexadecimal. Examples: 



You Type: :PC [ENTER] 
Screen Shows: DB : : PC 

C493 



You Type: : B CENTER] 
Screen Shows: D B : : B 

007E 



You Type: :SP (ENTER] 
Screen Shows: DB : :SP 

42FD 
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displays all registers and their contents. Example: 



You Type: : (ENTER) 

Screen Shows: DB : : 

PC = B2G5 A = 0i B = 0B CC = 80 

DP = 0C 
SP-0CF4 X = FF0D Y=000B 

U=00AE 

: < register > < expression > 

assigns a new value to a register. DEBUG evaluates the ex- 
pression and stores it in the specified register. When you name 
8-bit registers, the value of the expression must fit in a single 
byte. If it does not, the screen shows an error message, and the 
register does not change. Examples: 

You Type: : X #4 096 CENTER) 
Screen Shows: DB : : X #4 96 



Breakpoint Commands 



The breakpoint capabilities of DHBUG let you specify ad- 
dresses where you wish to suspend execution of the program 
under test and reenter DEBUG. When you encounter a break- 
point, the screen shows the values of the Registers MPU and the 
DB: prompt. 

After a breakpoint is reached, you can examine or change 
registers, alter memory, and resume program execution. You 
may insert breakpoints at up to 12 addresses. 

You can insert breakpoints by using the 6809 SWI instruction, 
which interrupts the program and saves its complete state on the 
stack. DHBUG automatically inserts and removes SWI instruc- 
tions at the right times; so you do not "see' 1 them in memory. 
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Because the SWIs operate by temporarily replacing an instruc- 
tion OP code, there are three restrictions on their use: 

1 . You cannot use breakpoints in programs in ROM. 

2. You must locate breakpoints in the first byte (OP 
code) of the instruction. 

3. You cannot utilize the SWI instruction in user pro- 
grams for other purposes. (You can use SWI2 and 
SWI3.) 

When you encounter the breakpoint during execution of the 
program under test, reenter DEBUG by typing <:>< register 
name> . The screen shows the program's register contents. 



B 

displays all present breakpoint addresses. 

B <expression> 

inserts a breakpoint at a specified expression. 

Examples: 

Insert a breakpoint at the specified expression: 
You Type: B 1C00 [ENTER) 
Screen Shows: DB: B 1C00 

Insert another breakpoint at the specified expression: 
You Type: B 4FD3 CENTER) 
Screen Shows: DB: B 4FD3 

Display the current value of Dot and its contents: 
You Type: . CENTER) 
Screen Shows: DB : ♦ 

1277 39 

Insert the breakpoints at Dot: 



You Type: B ♦ (ENTER) 
Screen Shows: DB: B ♦ 
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Display all present breakpoint addresses; 
You Type: B CENTER) 
Screen Shows: DB : B 

1C00 4FD3 1277 



K 

kills (removes) all breakpoints. 

K <expression> 

kills a breakpoint at the specified expression. Examples: 

Display all present breakpoint addresses: 
You Type: B [ENTER) 
Screen Shows: DBs B 

1C00 4FD3 1277 

Kill a breakpoint at the address specified by the expression: 
You Type: K 4FD3 CENTER) 
Screen Shows: D B ; K a F D 3 

Display all present breakpoint addresses: 
You Type: B (ENTER) 
Screen Shows: DB : B 

1C00 1277 

Kill all breakpoints: 



You Type: K CENTER) 
Screen Shows: DB : K 

Display all present breakpoint addresses: 
You Type: B INTER) 
Screen Shows: DB : B 
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Program Setup and Run Commands 



E module name 

prepares DEBUG for testing a specific program module. 

This command's function is similar to that of the OS-9 Shell in 
starting a program. It does not, however, redirect I/O or over- 
ride {#) memory size. The E command sets up a stack, 
parameters, registers, and data memory area in preparation for 
executing the program to be tested. The G command starts the 
program. 

Note: This command allocates program and data area memory 
as appropriate. The new program uses DEBUGS current stan- 
dard I/O paths, but can open other paths as necessary. In effect, 
DEBUG and the program become coroutines. 

This command is acknowledged by a register dump showing the 
program's initial register values. The G command begins pro- 
gram execution. The E command sets up the Registers MPU as 
if you had just performed an FSCHAIN service request as shown 
below: 



DP.U 



x,s 



direct page 



data area 



parameter area 



low 



high 



D = Parameter area size 
PC = Module entry point absolute address 
CC = (F = 0), (1 = 0) Interrupts disabled 
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Example- 
Display the program's initial register values: 
You Type: E my p ro # raw (ENTER) 
Screen Shows: D B : E my p ro ram 

SP CC A 6 DP 
X Y PC 
0CF3 C8 00 01 0C 
0CFF 0D00 BZia 



G 

goes to (resumes) program exceution after a breakpoint. If a 
breakpoint exists at the present program counter address, that 
breakpoint is not inserted so that it is not immediately recxe- 
cuted. A loop must contain at least two breakpoints if execution 
is to be suspended each time through the loop. 

Note: The E command is usually used before the first G com- 
mand to set up the program to be tested. DEBUG initially sets 
up a default stack; so G expression can be used to start a program 
using the results of the expression as a starting address. 
Examples: 

DB: G 4C00 
DB: G: PC -MOO 
DB: G[.] 

L module name 

links to the module. If successful, it sets Dot to the address of 
the first byte of the program and displays it. You can use L to 
find the starting address of an OS-9 memory module. 

Example: 

Link to the module FPMATH: 



You Type: L FPMATH (ENTER) 

Screen Shows: DB: LFPMATH 

EC00 87 
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Utility Commands 



C <expressionl> <expression2> 

performs a "walking bit" memory test and clears all memory 
between the two evaluated addresses. Expression! gives the 
starting address, and expression! gives the ending address, 
which must be higher. If any bytes fail the test, this command 
displays their address. Of course, you can test and clear only 
RAM memory. 

Warning: This command can be dangerous. Be sure which 
memory address you are clearing. 

Examples: 

Clear all memory between Addresses 2000 and 15FF: 
You Type: C 15FF 2000 CENTER) 
Screen Shows: DB: C 15FF 2000 

17E4 

17E7 

The screen's display of 17E4and 17E7 indicates bad memory at 
those addresses. 

Clear all memory between the last value of Dot and Address FF. 
You Type: C ♦ *+FF CENTER) 
Screen Shows: DB : C . *+FF 

The screen shows a blank line following the command line, 
which indicates good memory. 

M <expressionI> <expression2> 

produces a screen-sized tabular display of memory contents in 
both hexadecimal and ASCII form. 

The starting address of each line is on the left, followed by the 
contents of the subsequent memory locations. On the far right is 
the ASCII representation of the same memory locations. 

Periods are substituted for nondi splay able characters. The high 
order bit is ignored for the display of the ASCII character. 
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S <expressionl> ^expression! '> 

searches an area of memory for a 1- or 2 -byte pattern, beginning 
at the present Dot address. Expression I is the ending address of 
the search, and expression! is the data for which to search. If 
expression! is less than 256, a 1 -byte comparison is used; if it is 
greater than 256, a 2-byte comparison is used. If a matching 
pattern is found. Dot is set to its address, which is displayed. If a 
matching pattern is not found, the screen shows the DB: prompt. 



calls the OS-9 Shell, which responds with prompts for one or 
more command lines. 

$ Shell Command 

executes the command and returns to DEBUG. 

Also use $ to call the system utility programs and the Interactive 
Assembler from within DEBUG. Examples: 



You Type: $DIR (EHUR) 
Screen Shows: DB : $D I R 

DIRECTORY OF ♦ 00:00:21 
OSS BOOT CMOS SYS 

DEFS STARTUP OLDFILE 
NEUIFILE BUSINESS FILE1 

Q 

quits (leaves) DEBUG and returns to the OS-9 Shell. Example: 



You Type: Q INTER) 
Screen Shows: DB : 

OSS: 
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4 / Using Debug 



You use DEBUG primarily to test system memory and I/O 
devices, to "patch" the operating system or other programs, 
and to test hand-written or compiler-generated programs, 



Sample Program 



The simple assembly-language program shown below illus- 
trates the use of DEBUG commands. This program prints 
* 'HELLO WORLD" and then waits for a line of input. 





NAM 




EXAMPLE 




USE 


/D0/DEFS/0S9DEFS 


* Data 


Section 








ORG 







LINLEN 


RUB 


-y 


LINE LENGTH 


INPBUF 


RMB 


80 


LINE INPUT BUFFER 




RMB 


50 


HARDWARE STACK 


STACK 


EQU 


* -1 




DATMEM 


EQU 


♦ 


DATA AREA MEMORY E 



(3000 
0000 
0002 
0052 
00E7 
00E8 

* P r o a r a m Section 
000 87CD004 7 MOD END PGM » NAME »$ 11 ,$81 >ENTRY , DATMEM 

000D 4558414D NAME FCS /EXAMPLE/ MODULE NAME STR I NG 



0014 




ENTRY 


EQU 


* 


MODULE ENTRY POINT 


0014 


308D0020 




LEAX 


OUTSTR >PCR 


OUTPUT STRING ADDRESS 


0018 


108E000C 




LDY 


#STRLEN 


GET STRING LENGTH 


001C 


8G01 




LDA 


#1 


STANDARD OUTPUT PATH 


001E 


103F8C 




0S9 


I$WRITLN 


WRITE THE LINE 


0021 


2512 




BCS 


ERROR 


BRA IF ANY ERRORS 


0023 


3042 




LEAX 


INPBUF ,U 


ADDR OF INPUT BUFFER 


0025 


108E0050 




LDY 


#80 


MAX OF 80 CHARACTERS 


0029 


8G00 




LDA 


#0 


STANDARD INPUT PATH 


002B 


103F8B 




0S3 


I$READLN 


READ THE LINE 


002E 


2505 




BCS 


ERROR 


BRA IF ANY I/O ERRORS 


0030 


03F00 




STY 


LINLEN 


SAME THE LINE LENGTH 


0033 


CS00 




LDB 


#0 


RETURN WITH NO ERRORS 


0035 


103F0B 


ERROR 


053 


F$EXIT 


TERMINATE THE PROCESS 


0038 


48454C4C 


OUTSTR 


FCC 


/HELLO WORLD/ OUTPUT STRING 


0043 


0D 




FCB 


$0D 


END OF LINE CHARACTER 


000C 




STRLEN 


EQU 


♦-OUTSTR 


STRING LENGTH 


0044 


2G8A06 




EMOD 




END OF MODULE 


0047 




ENDPGM 


EQU 
END 


* 


END OF PROGRAM 
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A Session With DEBUG 



The following example illustrates how to use DEBUG with the 
program on the previous page. (The actual RAM address may 
vary depending on your computer's installation of OS-9.) 

OS9:DEBUG #2K 

Interactive Debugger 

DB: $LOAD/Dl/EXAMPLE 

DB: L EXAMPLE 

A900 87 

DB: 

A900 87 

DB: M . . +44 (dump program on display) 

A900 87CD0047000D1I81 ...G.... 

A908 6F00 140084455841 O....EXA 

A910 4D504CC5308D0020 MPL.O.. 

A918 I08E00OC8601 103F '? 

A920 8C251 23042 108E00 .%.0B... 

A928 5086001 03F8B2505 P...?.%. 

A930 I09F00C600 103F06 ?. 

A938 48454C4C4F20574F HELLO WO 

A940 524C440DDB72DDFF RLD..R.. 



DB: 



DB: 



E EXAMPLE 

SP CC A 

0DF3 C8 00 



A900 87 
DB: B .+2E 
DB: G 
HELLO WORLD 

hello computer 

QffillD 



(prepare to run program) 
B DP X Y U PC 

01 0D 0DFF 0E00 0D00 9214 



(set breakpoint at address A92E) 
(run program) 



BKPT: (breakpoint encountered) 

SP CC A B DP X Y U PC 

0DF3 CO 00 01 0D 0D02 0D00 0D00 922E 
DB: M :0 :U + 20 (display register area) 

A00 000 1 OD020000000C 

0A08 0CF400004C000000 ....L... 
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0A10 00000087CD002400 . 
OA18 OD11810C001201C2 
OA20 OOOOOOOOOFFOOFF 

DB: . :U + 2 

OA02 68 
DB: 

OA03 65 
DB: 

0A04 6C 
DB: 

0A05 6C 
DB: Q 

OS9: 



Patching Programs 



To "patch" a program (to change its object code), follow these 
five steps: 

1. Load the program into memory using OS-9's 
LOAD command. 

2. Link to and change the program in memory using 
DEBUG 1 s L and = commands. 

3. Save the new, patched version of the program on a 
disk file using OS-9's SAVE command. 

4. Update the program module's CRC check value 
using OS-9's VERIFY command. Be sure to use the 
U option. 

5. Set the module's execute status using OS-9'sATTR 
command. 

Step 4 is unique to OS-9 (as compared with other operating 
systems) and often overlooked. However, it is essential because 
OS-9 refuses to load the patched program into memory until its 
CRC check value is updated and correct. 
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The example that follows shows how the program on page 00 is 
"patched." In this case the LDY #80 instruction is changed to 
LDY #32. 



OS9 


DEBUG 


(call DEBUG) 


Interactive Debugger 




DB: 


$LOAD EXAMPLE 


(call OS-9 to load program) 


DB: 


L EXAMPLE 


(set dot to beg addr of program) 




2000 87 


(actual address will vary) 


DB: 


. . + 28 


(add offset of byte to change*) 




2028 50 


(current value is 00) 


DB 


-#32 


(change to decimal 12) 




2028 10 


(change confirmed) 


DB: 


$SAVE TEMP EXAMPLE 


(save on file called ''TEMP 11 ) 


DB: 


SVERIFY U <TEMP> 
NEWEX 


(update CRC and copy to "NEWEX") 


DB: 


$ATTR NEWEX E PE 


(set execution status) 


DB: 


$DEL TEMP 


(delete temporary file) 


DB: 


q 


(exit DEBUG) 



Patching OS-9 Component Modules 



Patching modules that are part of OS-9 (modules contained in 
the OS-9 Boot file) is a bit trickier than patching a regular 
program because you must use the COBBLER and OS-9GEN 
programs to create a new OS-9 Boot file. The example below 
shows how an OS-9 "device descriptor" module is permanent- 
ly patched, in this case to change the upper-case lock of the 
device /TERM from on to off. This example assumes that a 
blank freshly formatted diskette is in Drive 1 (/Dl). 

Caution: Always use a copy of your OS-9 System Disk when 
patching, in case something goes wrong. 



OS9: DEBUG (ENTEE) 


(call DEBUG) 


Interactive Debugger 




DB: L TERM tENJERJ 


(set dot to addr of TERM module) 


CA82 87 


(actual address will vary) 


DB; . . +13 (ENTER) 


(add offset of byte to change*) 


CA95 01 


(current value is 01) 


DB; =1 (INTER) 


(change value to 01 for "OFF ,, ) 


CA96 01 




DB: - (INTER) 


(move back one byte) 


CA95 00 


(change confirmed) 


DB: Q (ENTH) 


(exit DEBUG) 


OS9: COBBLER /Dl CENTER! 


(write new bootfile on /Dl) 
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0S9: VERIFY </Dl/OS9BOOT >/DOFTEMP U fE NTER) 

{update CRC value) 
OS9:DEL /D1/OS9BOOT CENTER] (delete old boot file) 
OS9:COPY /DO/TEMP/D 1/OS9BOOT 

(install updated boot file) 

Then you can use the Dsave command to build a new systems 
disk. 
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Appendix / Debug Command 

Summary 



(SPACEBAR) expn 



Evaluate; display in hexadecimal 
and decimal. 



Dot Commands 



. expression 
~ expression 

CENTER) 



Display Dot address and 

contents, 
Restore last DOT, display 

address and contents. 
Set Dot to result, display address 

and contents. 
Set memory at Dot to result. 
Decrement Dot, display address 

and contents. 
Increment Dot, display address 

and contents. 



Register Commands 



'.register 



'.register 
expression 



Display all register contents. 

Display specific register 

contents. 

Set register to result. 



Program Setup and Run Commands 



E module name 

G 

G expression 

L module name 



Prepare for execution. 
Go to program. 

Go to program at result address. 
Link to module named, display 
address. 



Breakpoint Commands 



B 



B expression 

K 

K expression 



Display all breakpoints. 

Set breakpoint at result address. 

Kill all breakpoints. 

Kill breakpoint at result address. 
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Error Codes 



Utility Commands 

M expression! Display memory dump in tabular 

form . expression! 

C expression 1 Clear and test memory 

expression! 

S expression! Search memory for pattern 

expression! 

$ text Call OS-9 Shell 

Quit (exit)DEBUG 



DEBUG detects several types of errors and displays a corres- 
ponding error message and code number in decimal notation. 
The various codes and descriptions are listed below. Error codes 
other than those listed are standard OS-9 error codes returned by 
various system calls. 

ILLEGAL CONSTANT: The expression included 
a constant that had an illegal character or that was 
greater than 65,535. 

1 DIVIDE BY ZERO; A division was attempted us- 
ing a divisor of zero. 

2 MULTIPLICATION OVERFLOW: The product of 
the multiplication was greater than 65,535. 

3 OPERAND MISSING: An operator was not fol- 
lowed by a legal operand. 

4 RIGHT PARENTHESIS MISSING: Parentheses 
were misnested. 

5 RIGHT BRACKET MISSING: Brackets were 

misnested. 

6 RIGHT ANGLE BRACKET MISSING: A byte- 
indirect was misnested. 

7 INCORRECT REGISTER: A misspelled, missing, 
or illegal register name followed the colon. 
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8 BYTE OVERFLOW: An attempt was made to 
store a value greater than 255 in a byte-sized 
destination. 

9 COMMAND ERROR: A command was mis- 
spelled, missing, or illegal. 

1 NO CHANGE: The memory location did not match 
the value assigned to it. 

11 BREAKPOINT TABLE FULL: The maximum 
number of 12 breakpoints already exist. 

12 BREAKPOINT NOT FOUND: No breakpoint 
exists at the address given. 

13 ILLEGAL SWI: An SWI instruction was encoun- 
tered in the user program at an address other than a 
breakpoint. 
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TEXT EDITOR INDEX 



Command Series Repetition 26 
Conditionals 26 
Commands 4 
Entering 4 
Parameters 6 
Numeric 6 
String 6 



Deleting Lines 15 
Displaying Text 1 1 



Edit Macros 30 

Headers 31 

Parameter Passing 31 
Edit Pointers 4 

Moving 12 
Editor Error Messages 66 

I 

Inserting Lines 15 

M 

Manipulating Multiple Buffers 21 

S 

Searching 17 
Substituting 17 
Syntax Notation 7 



Text Buffers 3 

Text File Operations 23 



169 



ASSEMBLER INDEX 



Addressing Modes 83 

Accumulator Addressing 83 

Accumulator Offset Indexed 89 

Auto-Decrement Indexed 90 

Auto-Increment Indexed 90 

Constant Offset Indexed 87 

Direct Addressing 85 

Extended Addressing 84 

Extended Indirect Addressing 84 

Immediate Addressing 83 

Indexed Addressing 87 

Inherent Addressing 83 

Program Counter Relative Indexed 88 

Register Addressing 86 

Relative Addressing 84 
Assembler Directive Statements 97 
Assembler Input Files 73 



Data Sections 1 1 5 
DEFS Files 105 



Error Messages 121 
Evaluation of Expressions 79 
Expression Operands 79 



Operating Modes 74 
Operators 80 



Position Independent Mode 116 
Program Area 116 
Program Sections 115 
Programming Techniques 115 
Psuedo Instructions 91 
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Source Statement Fields 77 

Comment 78 

Label 77 

Operand 78 

Operation 78 
Symbolic Names 81 
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INTERACTIVE DEBUGGER 
INDEX 



B 

Basic Concepts 141 
Breakpoint Commands 152 



Calculator Commands 147 
Calling DEBUG 141 
Change Commands 148 



Debug, Calling 141 
Debug Commands 147 
Dot Commands 148 



Expressions 143 
Constants 143 
Forming Expressions 145 
Indirect Addressing 146 
Operators 145 
Register Names 144 
Special Names 144 

M 

Memory Examine Commands 148 



Patching OS-9 Component Modules 162 
Patching Programs 161 
Program Setup Commands 155 
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Register Change Commands 151 
Register Examine Commands 151 
Run Commands 155 

U 

Utility Commands 157 
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RADIO SHACK, A DIVISION OF TANDY CORPORATION 



U.S.A.: FORT WORTH, TEXAS 76102 
CANADA: BARRIE, ONTARIO L4M 4W5 



AUSTRALIA 



91 KURRAJONG ROAD 
MOUNT DRUITT, N.S.W. 2770 



TANDY CORPORATION 

BELGIUM 

PARC INDUSTRIEL DE NANINNE 
5140 NANINNE 



U. K. 



BILSTON ROAD WEDNE5BURY 
WEST MIDLANDS WS10 7JN 



9/84-TM 



Printed in U.S.A. 



TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK 
QOMPUTHR EOUIPWEWT ANO SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 

STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 



LIMITED WARRANTY 

CUSTOMER OBLIGATIONS 

A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the 
"Equip-mertn , and any copies of Radio Stack sgflwaft included with the Equipment or licensed 
separately (the "Software") meets the specif [cations, capacity, capabilities, versatility, ami other 
retirements of CUSTOMER. 

B. CUSTOMER assumed full responsibility for trie condition and effectiveness of the operating 
environment In which the Equipment and Software are to function, and for its installation. 

RADIO SHACK MMITID WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the dale of the Radio Shack sales document 
ffiostad upon purchase of ttw Equipment RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from many factu ring 
defects. THIS WARRANTY 1$ ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment's case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. ff a manufacturing defect 
is discovered during the staled warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the safes document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect fay repair, replacement, or refund of tfw purchase price, at RADIO 
SHACK'S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable items. 

B. RADIO SHACK mains no warranty as to the design, capability, capacity, or suitability lor use of 
the Software, except as provided in mis paragraph. Software is licensed on an "AS IS" basis, 
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software 
TmmfocturinQ defect, is Us repair ot Tepiarnnern wmin thirty {30) calendar days of the Hate of the 
Radio Shack sales document received upon iicense of the Software, The defective Software shall 
be returned to a Ratio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

C. Except as provided hereto no employee, agent, franchisee, dealer or other person is authorfeert to 
give any warranties of any nature on behalf of RADIO SHACK. 

D Except as provided herein, RADIO SMACK MAKES HO WARRANTIES, IMCLUDIMQ WARRANTIES 

OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 
E. Some states do not a/low limitations on how long an Implied warranty lasts, so the above 

limitation^) may not apply to CUSTOMER. 

III. LIMITATION OF Lf ABfLIIY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY Oft RESPONS^UTf 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO ftE GAUSEO OtftECTLY QR WOlRECTLY &Y 
"EQUIPMENT" OR "SOFTWARE" SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT UMITEQ TO, ANY INTERRUPTION QF SERVICE, LOSS QF BUSfNESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE "EQUIPMENT" OR "SOFIWARE". IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL. OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WfTH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE "EQUIPMENT" 
OR "SOFIWARE". 

continued 



NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR "EQUIPMENT' OR "SOFTWARE" 
INVOLVED. 

B. RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

D. Some slates do not allow the limitation or exclusion of incidental or consequential damages, so the 
above iimitation(s) or exclusions) may not apply to CUSTOMER 



IV. RADIO SHACK SOFTWARE LICENSE 

RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on one computer, subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

B. Title to the medium on which the Software Js recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software, 

C. CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals If the Software permits this function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
am computer and as is specifically provided In this Software License. Customer is expressly 
prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or if additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted to make a limited number of additional copies for 
CUSTOMER'S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software tor each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on ail copies of the Software. 



APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party tor lease to 
CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall Inure to the benefit of RADIO 
SHACK, the author, owner and/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 

STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER may have other rights which vary from state to state. 
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Introduction 



OS-9 is a versatile multiprogramming/multitasking operating 
system for the TRS-80 Color Computer. It is well-suited for a 
wide range of applications. In addition to multiprogramming, 
its main features are: 

• Comprehensive management of all system resources: 
memory, input/output, and CPU time 

• Efficient operation in typical microcomputer con- 
figurations 

• An expandable, device-independent unified I/O system 



History and Design Philosophy 



In the few years since its introduction, OS-9 has developed a 
worldwide user base of thousands. It is especially popular in the 
engineering, research, education, and scientific applications. 

Microware and Motorola modeled OS-9 upon Bell Telephone 
Laboratories' UNIX operating system, which is becoming 
widely recognized as a standard for mini and micro multipro- 
gramming operating systems. Although its implementation is 
different, OS-9 retains the overall concept and user interface of 
UNIX. If you are experienced with UNIX, you should feel quite 
comfortable with OS-9. 

In addition, OS-9 introduces some important features to make 
the most of the 6809 microprocessor. Perhaps the most innova- 
tive of these isOS-9's "memory module" management system. 
This system provides extensive support for modular software 
techniques, which encourage simplified and more reliable 
programming. 

The OS-9 modules are introduced in Chapter I of this manual 
and are discussed in detail throughout. 



About This Manual 



Special Notations 



This manual provides all the information necessary to install, 
maintain, expand, or write assembly-language programs for 
OS -9 systems. It assumes you are familiar with the 6809 
architecture, instruction set, and assembly language. 



For your convenience, the following special notations are used 
in this manual. 

lower-case italics 

represent words, letters, characters, or values that you supply. 

$nn 

specifies that nn is a hexadecimal number. All other numbers in 
the text of this manual are in decimal (base 10) form, unless 
otherwise noted. 
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1 / System Organization 



OS-9 is composed of a group of modules, each of which has 
specific functions. The illustration below shows the major mod- 
ules. Actual module names are capitalized. 



Color Computer OS-9 Modules 
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Device Descriptors 



Kernel, Clock Module, and INIT 



The first level contains the "kernel, 
TNIT." 



'clock module," and 



The kernel provides basic system services, such as multitasking 
and memory management. It links all other system modules. 

The clock module is a software handler for the specific real- 
time-clock hardware. 

INIT is an initialization table used by the kernel during system 
startup. It loads initial tasks and specifies initial table sizes and 
initial system device names. 



Input/Output Modules 



IOMAN 



The remaining modules make up OS-9's unified I/O system. 
They are defined briefly here and are discussed in detail in 
Chapter 4 . 



The second level (the level below the kernel) contains the 
"input/output" manager (IOMAN). IOMAN provides com- 
mon processing of all I/O operations. It is required if any 
OS-supported I/O is to be performed. 



File Managers 



The third level contains the "file managers." File managers 
perform I/O request processing for similar classes of I/O 
devices. 

The Random Block File Manager (RBFMAN) processes all disk 
I/O operations. The Sequential Character File Manager 
(SCFMAN) handles all non-disk I/O operations that basically 
operate a character at a time, such as terminal and printer 
operations. The Pipe File Manager (PIPEMAN) handles pipes, 



Device Drivers 



which are memory buffers that act like files for inter-process 
data transfers. 



The fourth level contains the "device drivers. 1 ' Device drivers 
handle basic physical I/O functions for specific I/O controller 
hardware. You may add your own customized drivers, or you 
may receive new drivers with accessory hardware devices. 



Device Descriptors 



Shell 



Boot 



The fifth level contains the "device descriptors/ 1 These mod- 
ules are small tables that associate each I/O port with its logical 
name, device driver, and file manager. They also contain the 
port's initialization data and physical address. 

When the device descriptors are used, only one copy of each 
driver is required for each type of I/O controller, regardless of 
the number of controllers the system uses. 



The "shell" (not shown) is the command interpreter. It is 
technically a program and not part of the operating system itself, 
and is described fully in the OS -9 Commands manual. 



All modules are loaded into RAM during system startup by the 
disk bootstrap module, "Boot." Boot (not shown) is initially 
loaded into memory by the Color BASIC DOS command. 



2 / The Kernel 



The ''nucleus" of OS-9 is the kernel, which supervises the 
system and manages system resources. It is about 3K bytes long 
and is contained in the OS9 and OS9P2 modules, with Boot, at 
memory addresses $F000 - $FEFF. 

The kernel's main functions are: 

• System initialization after reset 

• System call processing 

• Memory management 

• Multiprogramming (6809 management) 

• Interrupt processing 

Note: Input/output functions are not included in the 
list because the kernel does not directly process them. 
Instead, it passes I/O system calls to IOMAN for 
processing. 



System Initialization 



After a hardware reset, the kernel initializes the system. This 
involves the following: locating modules loaded in memory 
from the OS-9 Boot file, allocating memory for internal tables, 
and running the system startup task (SYSGO). The INIT mod- 
ule is used during startup to specify initial table sizes and system 
device names. 

The SYSGO program does the following: 

1 . Calls the shell and initializes the high-level system. 

2. Starts the first user process. 

3. Remains in the Wait state to make sure that all uses do 
not terminate and thus halt the system. SYSGO can 
keep the system going by restarting the first user 
process. 



System Call Processing 



"System calls" are used to communicate between OS-9 and 
assembly-language programs for such functions as memory 
allocation and process creation. In addition to I/O and memory 
management functions, system calls have other functions. 
These include interprocess control and timekeeping. 

System calls use the SWI2 instruction followed by a constant 
byte representing the code. Parameters for system calls are 
usually passed in the 6809 register. 



OS9Defs and Symbolic Names 



A system-wide assembly-language equate file called OS9Defs 
defines symbolic names for all system calls. This file is included 
when assembling hand- written or compiler-generated code. The 
OS-9 assembler has a built-in macro to generate system calls. 
For example: 

OS9 I$read 

is recognized and assembled as the equivalent to: 

SWI2 
FCB I$read 



Types of System Calls 



System calls are divided into two categories, "I/O" calls and 
"function 11 calls. 

I/O calls perform various input/output functions. Calls of this 
type are passed by the kernel to IOMAN for processing. The 
symbolic names for I/O calls begin with 1$. For example, the 
Read system call is called I$read. 



Function calls perform memory management, multi- 
programming, and other functions. Most are processed by the 
kernel. The symbolic names for function calls begin with F$. 
For example, the Link system call is called F$link. 

The function calls include "user" calls and privileged "system 
mode 1 ' calls. (See Chapter 8 for more information.) 



Memory Management 



Memory management is an important operating system func- 
tion. Using memory modules, OS-9 manages the logical con- 
tents of memory and the physical assignment of memory to 
programs. 

All programs that are loaded must be in the memory module 
format. This format allows OS-9 to maintain a module direc- 
tory. The directory contains information about the module, 
including its name and address and the number of processes 
using it. 

When a module no longer is needed, OS-9 deallocates its part of 
memory and removes its name from the module directory (ex- 
cept ROM, which is discussed later). 

The memory modules are the foundation of OS-9\s modular 
software environment. These are some advantages of memory 
management: 

• Automatic run-time "linking" of programs to libraries 
of utility modules 

• Automatic "sharing 11 of reentrant programs 

• Replacement of small sections of large programs for 
update or correction (even when in ROM). 



Memory Use 



OS-9 reserves some space at the top and bottom of RAM for its 
own use. The amount depends on the sizes of system tables that 
are specified in the INIT module. 

All other RAM is pooled into a "free memory" space. As 
memory is allocated or deallocated, it is dynamically taken from 
or returned to this pool. 

The basic unit of memory allocation is the 256-byte "page.' 1 
OS-9 always allocates memory in whole numbers of pages. 

The data structure used to keep track of memory allocation is a 
32-byte "bit map" located at $0200 - $02 IF. Each bit in this 
table is associated with a specific page of memory. 

Cleared bits indicate that the page is free and available for 
assignment. Set bits indicate that the page is in use or that no 
RAM memory is present at that address. 

Memory is allocated automatically when any of the following 
occurs; 

• Program modules are loaded into RAM 

• Processes are created 

• Process request additional RAM 

• OS-9 needs I/O buffers or larger tables 

Each of these functions usually has an inverse function that 
causes memory to be deallocated and returned to free memory. 

In general, memory for program modules and buffers is allo- 
cated from high addresses downward. Memory for process data 
areas is allocated from lower addresses upward. 

On the next page is a map of a "typical" system. Actual 
memory sizes and addresses may vary depending on the exact 
system configuration. 



Color Computer OS-9 Typical Memory Map 
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Multiprogramming 



OS-9 is a multiprogramming operating system. This means 
several independent programs called "processes" can be ex- 
ecuted at the same time. By issuing the appropriate system call 
to OS-9, each process can have access to any system resource. 



Process Creation 



Multiprogramming functions use a hardware real-time clock 
that generates interrupts at a regular rate of 60 times per second. 
Therefore, 6809 time usually is divided into periods of 16.67 
milliseconds. These periods are called "ticks." 

"Active" processes (those not waiting for some event) are run 
for a specific system-assigned period called a "time slice. The 
length of the time slice depends on a process' priority relative to 
all other active processes. Many OS-9 system calls arc available 
to create, terminate, and control processes. 



A process is created when an existing process executes a Fork 
system call (F$fork). This call's main argument is the name of 
the program module that the new process is to execute first (the 
"primary module"). 

Find the Module. OS-9 first attempts to find the module in the 
module directory, If it does not find the module, OS-9 usually 
attempts to load into memory a mass- storage file, giving it the 
requested module name as a filename. 

Assign a Process Descriptor. Once OS-9 finds the module, it 
assigns the process a data structure called a "process descrip- 
tor." This is a 64-byte package that contains information about 
the process, its state, memory allocations, priority, queue poin- 
ters, and so on. 

OS-9 automatically initializes and maintains the process de- 
scriptor. The process itself cannot access the descriptor; it has 
no need to do so. 

Allocate RAM. The next step is allocation of RAM for the 
process. The primary module's header contains a storage size. 
OS-9 uses this size unless the Fork system call asked for a larger 
area. OS-9 then attempts to allocate a contiguous memory area 
of the specified size from the free memory space. 

Create or Abort. If OS-9 can perform all of the previous steps, 
it adds the new process to the active process queue for execution 
scheduling. If it cannot, it aborts the creation. The process that 
originated the Fork is informed of the error. 
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Assign Process ID and User ID. OS-9 assigns the new process 
a unique number called a "process ID.' 1 Other processes can 
communicate with the process by referring to its ID in various 
system calls. 

The process also has a "user ID/ 1 which is used to identify all 
processes and files belonging to a particular user. The user ID is 
inherited from the parent process. 



Process Termination 



Process States 



A process terminates when it executes an Exit system call 
(FSexit) or when it receives a fatal signal. The termination 
closes any open paths, deallocates memory used by the process, 
and unlinks the primary module. 



At any instant a process can be in one of three states: 

• Active (The process is ready for execution.) 

• Waiting (The process is suspended until a "child pro- 
cess" terminates or a signal is received.) 

• Sleeping (The process is suspended for a specific 
period of time or until a signal is received.) 

Each state has its own queue, a linked list of "descriptors'' of 
processes in that state. State changes arc performed by moving a 
process descriptor to another queue. 

The Active State. Each active process is given a time slice for 
execution, according to its priority relative to all other active 
processes. The scheduler, which is in the kernel, makes sure 
that all active processes, even those of low priority, get some 
CPU time. 

The Wait State. This state is entered when a process executes a 
Wait system call (F$wait). The process remains suspended until 
one of its "child" processes dies or until it receives a "signal." 
(See the "Signals" section below.) 
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The Sleeping State. This state is entered when a process ex- 
ecutes a Sleep system call (FSsleep), which specifies the num- 
ber of ticks for which the process is to remain suspended. The 
process remains asleep until the specified time has elapsed or 
until it receives a siiinal. 



Execution Scheduling 



Signals 



The OS- ( ) scheduler uses an algorithm that ensures that all active 
processes get some execution time. 

All active processes are members of the ^ active process 
queue, " which is kept sorted by process ^age." Age is a count 
of how many process switches have occurred since the process' 
last time slice. When a process is moved to the active process 
queue from another queue, its age is set according to its priority 
— the higher the priority, the higher the age. 

Whenever a new process becomes active, the ages of all other 
active processes are incremented. When the executing process' 
time slice has elapsed, the scheduler selects the next process to 
be executed (the one with the next highest age. the first one in 
the queue). At this time the ages of all other active processes are 
incremented. (Ages are never incremented beyond 255, 
however. ) 

An exception is a newly active process that was deactivated 
while in the system state. Such a process is given higher priority 
because it usually is executing critical routines that affect shared 
system resources. Therefore, it could be blocking other unre- 
lated processes. 

When there are no active processes, the kernel sets itself up to 
handle the next interrupt and then execute a Cwai instruction, 
which decreases interrupt latency time. 



A signal is an asynchronous control mechanism used for inter- 
process communication and control. It behaves like a software 
interrupt (it can cause a process to suspend a program, execute a 
specific routine, and afterward return to the interrupted 
program). 
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Signals can be sent from one process to another process by the 
Send system call (F$send). Or, they can be sent from OS-9 
service routines to a process. 

The signal can convey status information in the form of a 1 -byte 
numeric value. Some of the signal "codes" (values) are prede- 
fined, but you may define most. The signal codes are: 

= Kill (aborts the process; is non-intcreeptablc) 

1 = Wakeup (wakes up a sleeping process) 

2 = Keyboard abort 

3 — Keyboard interrupt 

4 = User-defined (255) 

When a signal is sent to a process, the signal is noted and saved 
in the process descriptor. If the process is in the sleeping or 
waiting state, it is changed to the active state. When it gets its 
next time slice, the signal is processed. 

What happens next depends on whether or not the process has 
set up a "signal intercept trap" (signal service routine) by 
executing an Intercept system call (FSicpt). 

If it has set up a signal intercept trap, the process resumes 
execution at the address given in the Intercept call. The signal 
code is passed to this routine, which should terminate with an 
RTI instruction to resume normal execution of the process. 

Note: A wakeup signal activates a sleeping process. It 
does not vector through the intercept routine. 

If it has not set up a signal intercept trap, the process is aborted 
immediately. It is also aborted if the signal code is zero. If the 
process is in the system mode, the abort is deferred (it dies upon 
return to the user state). 

A process may have a signal pending (usually because it has not 
been assigned a time slice since the signal was received). If it 
does, and another process tries to send it another signal, the new 
signal is aborted, and the Send system call returns an error. The 
sender should then execute a Sleep system call for a few ticks 
before trying to send the signal again. This gives the destination 
process time to process the pending signal. 
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Interrupt Processing 



Interrupt processing is another important function of the kernel, 
OS-9 sends each hardware interrupt to a specific address. This 
address, in turn, specifies the address of the device service 
routine to he executed. This is called ' 'vectoring 1 ' the interrupt. 
The address that points to the routine is called the "vector." It 
has the same name as the interrupt. 



Physical Interrupt Processing 



Addresses $FFF0 through $FFFF (in the Color BASIC ROM) 
contain the hardware vectors required by 6809. Each address 
points to a RAM vector, as follows: 

Interrupt Vector 

SWI3 (Software Interrupt 3) $0100 

SWI2 (Software Interrupt 2) $0103 

FIRQ (Fast Interrupt Request) $01 OF 

IRQ (Interrupt Request) $010C 

SWI (Software Interrupt) $0106 

NMI ( Non-Maskable Interrupt) $0109 

OS-9 initializes each of these RAM vectors to point to a specific 
service routine in the kernel. 

Software Interrupts (SWI, SYVI2, and SWI3.) The software 
interrupts are vectored to user-definable addresses, which are 
local to each procedure. SWI2, however, usually is used for 
OS-9 system calls. 

The SWI, SWI2, and SWI3 vectors point to routines that read 
the corresponding pseudo vector from the process' descriptor 
and dispatch to it. This is why the Set SWI system call (F$sswi) 
is local to a process; it only changes a pseudo vector in the 
process descriptor. 

FIRQ Interrupt. The system uses the FIRQ interrupt. The 
FIRQ vector, which points to an RT1 instruction, is not available 
to you. 
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IRQ Interrupt. Most OS-9 I/O devices generate IRQ inter- 
rupts. The IRQ vector points to the real-time clock and keyboard 
scanner routines. These routines, in turn, jump to a special IRQ 
polling system which determines the source of the interrupt. The 
polling system is discussed in the next section, k 'Logical Inter- 
rupt Polling System." 

NMI Interrupt. The system uses the NMI interrupt. The NM1 
vector, which points to the disk driver interrupt service routine, 
is not available to vou. 



Logical Interrupt Polling System 



Because most OS-9 I/O devices use IRQ interrupts, OS-9 in- 
cludes a sophisticated polling system. The IRQ polling system 
automatically identifies the source of the interrupt, and then 
executes its associated user- or system-defined service routine. 

The Polling Table. The information required for IRQ polling is 
maintained in a data structure called the "IRQ polling table/ 1 
The table has a 9-byte entry for each device that might generate 
an IRQ interrupt. The table size is permanent and is defined by 
an initialization constant in the INIT module. 

Each entry in the polling table is given a number from (lowest 
priority) to 255 (highest priority). In this way, the more impor- 
tant devices (those that have a higher interrupt frequency ) can be 
polled before the less important ones. 

Each entry has 6 variables: 

• Foiling Address — points to the device's status regis- 
ter. The register must have a bit or bits that indicate it is 
the source of an interrupt. 

• Flip Byte — selects whether the bits in the device 
status register indicate active when set or active when 
cleared. If a bit in the flip byte is set, it indicates that the 
task is active whenever the corresponding bit in the 
status register is clear (and vice versa). 

• Mask Byte — selects one or more bits within the 
device status register that are interrupt request flag(s). 
One or more set bits identify which task or device is 
active. 
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• Service Routine Address — points to the device's 
interrupt service routine. You supply this address. 

• Static Storage Address — points to the permanent 
storage area required by the device service routine. 
You supply this address. 

• Priority — sets the order in which the devices are to be 
polled (a number from to 255). 

Polling the Entries. When an IRQ interrupt occurs, the polling 
system is entered via the corresponding RAM interrupt vector. 
It starts polling the devices in order. Each entry's status register 
address is loaded into Accumulator A, using the device address 
from the table. 

Then, an Hxclusive-OR operation using the flip byte is ex- 
ecuted, followed by a Logical- AND operation using the mask 
byte. If the result is non-zero, the device is assumed to be the 
cause of the interrupt. 

The device's memory address and service routine address are 
read from the table and executed. 

Note: The interrupt service routine should terminate with 
an RTS instruction, not an RTI instruction. 

Adding Entries to the Table. Using the Set IRQ system call 
(F$irq). you can make entries to the IRQ polling table. Set IRQ 
is a privileged system call, which can be executed only when 
OS-*) is in system mode (which is the case when device drivers 
are executed). 

Note: The actual code for the interrupt polling system is 
located in the IOMAN module. The kernel OS9 and 
OS9P2 modules contain the physical interrupt processing 
routines. 



16 



3 / Memory Modules 



In Chapter 2, you learned that OS-9 is based on the concept that 
memory is modular. This means that each program is consid- 
ered to be an individual, named "object." 

You also learned that all objects that are loaded into memory 
must be in the module format. This format lets OS-9 manage the 
logical contents of memory, as well as the physical contents. 
Module types and formats are discussed in detail in this chapter. 



Module Types 



There are several types of modules, each of which has a differ- 
ent use and function. These are the main requirements of a 
module: 

• It cannot modify itself. 

• It must be position-independent so OS-9 can load or 
relocate it wherever space is available. In this respect, 
the module format is the OS-9 equivalent of "load 
records" used in older operating systems. 

A module need not be a complete program or even 6809 
machine language. It may contain BAS1C09 "I-code," con- 
stants, single subroutines, and subroutine packages. 
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Module Format 



bach module has three parts; a "module header/" a "module 
body," and a "cyclic-redundancy-eheek value" (CRC value). 

Module Format 



Module Header 



Program 
or Constants 



CRC Value 



Module Header 



At the beginning of the module (lowest address) is the module 
header. Its form depends upon the module's use. 

The header contains information about the module and its use. 
This includes the following: 

• Size 

• Type (machine language, BASIC09 compiled code, 
and so on) 

• Attributes (executable, reentrant, and so on) 

• Data storage memory requirements 

• Execution starting address 

Usually, you don't need to write routines to generate the mod- 
ules and headers. Most OS-9 programs — including BASIC09, 
Pascal, C\ and the assembler — do this automatically. 
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Module Body 



CRC Value 



The module body contains the program or constants. It usually 
is pure code. The module name string is included somewhere in 
this area. 



The last three bytes of the module are the Cyclic Redundancy 
Check (CRC) value. The CRC value is used to verify the 
integrity of a module. 

The 24-bit CRC is performed over the entire module from the 
first byte of the module header to the byte just before the CRC 
itself. The CRC polynomial used is $8<M)FE3. 

As with the header, you usually don't need to write routines 
to generate the CRC value. Most OS-9 programs do this 
automatically. 



Module Headers: Standard Information 



The first nine bytes of all module headers are defined as follows; 



Relative 


Use 


Address 




$00, $01 


Sync bytes ($S7.$CD) 


$02, $03 


Module si/c 


$04 ,.$05 


Offset to module name 


$06 


Module type / Language type 


$07 


Attributes . Revision level 


$08 


Header eheek 



Sync Bytes. Specify the location of the module, (The first sync 
byte is the start of the module.) These two bytes are constant. 

Module Size. Specify the size of the module in bytes (includes 
CRC). 
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Offset to Module Name. Specifies the address of the module 
name string relative to the start of the module. The name string 
can be located anywhere in the module and consists of a string of 
ASCII characters having the most significant bit set on the last 
character. 

Type/Language Byte. Specifies the type and language of the 
module. 

The four most significant bits o\^ this byte indicate the type. 
Bight types are pre-defined. Some of these are for OS-9's 
internal use only. The type codes are given here: 

Code Moduli. 1 Type 

$01 Program module 

$02 Subroutine module 

$03 Multi- module (for future use) 

$04 Data module 

$05-$0B User-definable 

$0C OvS-9 system module 

$01) OS-9 file manager module 

$0H OS- device driver module 

%0V OS -9 device descriptor module 

The four least significant bits of this byte indicate the language. 
The language codes are given here: 

Code Language 



$00 


Data (non-executable) 


$01 


6809 object code 


$02 


BASIC09 1 code 


$03 


PASCAL P-eode 


$04 


COBOL I-eode 


$05-$ 15 


Reserved for future use 



By checking the language type, high-level language run-time 
systems can verify that a module is the correct type before 
attempting execution. BASIC09, for example, may run either 
I-code or 6809 machine language procedures arbitrarily by 
cheeking the language type code. 
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Attributes / Revision Byte. Specifics the attributes and revi- 
sion level of the module. 

The four most significant bits of this byte are reserved for 
module attributes. Currently, only Bit 7 is defined. When set. it 
indicates the module is reentrant and therefore "shamble/'' 

The four least significant bits of this byte are a revision level 
from to 15. If two or more modules have the same name, type, 
language, and so on. ()S-°- keeps in the module directory only 
the module having the highest revision level. Therefore, you 
can replace or patch a ROM module, simply by loading a new. 
equivalent module that has a higher revision level. 

Note: A previously linked module cannot be replaced 
until all processes linked to it have unlinked it (after its 
link count goes to /cm). 

Header Cheek. Specifies the one's complement of the Kxelu- 
sive-OR of the previous eight bytes. 



Module Headers: Type-Dependent Information 



More information usually follows the first nine bytes of the 
header. The layout and meaning vary, depending on the module 
type. 

Module types SOC-SOF (system module, file manager module, 
device driver module, and device descriptor module) are used 
by OS-9 only. Their formats are given later in the manual. 

Module types SOI through $0B have the general-purpose 
'TiNer 1 ' format (executable format) shown on the next page. 
This format is used often for OS-9 programs that are called by 
Fork or Chain (F$lbrk and FSchain). 
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Executable Memory Module Format 



Use 



Relative 
Address 



$00 
$01 


— 


Syne Bytes ($87CD) 


$02 
$03 




Module Size (bytes) 


$04 
$05 


— 


Module Name Offset — ' 


$06 




Type 


Language 


$07 


Attributes 


Revision 


$08 


Header Parity Check 


$09 
$0A 


— 


Execution Offset 


$0B 
$0C 




Permanent Storage Size """" 


$0D 




(Additional optional 

header extensions 

loeated here) 




Module Body 

object code, constants, 

and so on 






CRC Check Value 



Check 
Range 



header 
parity 



module 
CRC 
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As you can see from the chart on the previous page, this module 
format has two extra bytes in its header. They are: 

$09,$0A Execution offset 

$0B,$()C Permanent storage size 

Execution Offset. The program or subroutine's offset starting 
address, relative to the first byte of the sync code. A module that 
has multiple entry points (such as cold start and warm start) may 
have a branch table starting at this address. 

Permanent Storage Size. The minimum number of bytes of 
data storage required to run. Fork and Chain use this number to 
allocate a process' data area. 

If the module will not be directly executed by a Fork or Chain 
system call (for instance a subroutine package), this entry is not 
used by OS-9. It is commonly used to specify the maximum 
stack size required by reentrant subroutine modules. The calling 
program can check this value to determine if the subroutine has 
enough stack space. 



ROM Modules 



When OS-9 starts after a system reset, it searches the entire 
memory space for ROM modules. It finds them by looking for 
the module header sync code <$87,$CD). 

When this byte pattern is detected, OS-9 checks the header to 
see if it is correct. If it is, the system obtains the module size 
from the header and performs a 24-bit CRC over the entire 
module. If the CRC matches, OS-9 considers the module to be 
valid and enters it into the module directory. All ROM modules 
that are present in the system at startup are automatically in- 
cluded in the system module directory. 
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After the module search, OS-9 links to the component modules 
it found. This is the secret to OS-9*s ability to adapt to almost 
any 6809 computer. It automatically locates its required and 
optional component modules and rebuilds the system each time 
it is started. 

At startup. OS-9 also searches ROM for non-system modules.lt 
locates any software you supply and, if the module's header and 
CRC information is correct, enters it into the module directory. 
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4 / OS-9's Unified Input/Output 
System 



In Chapter 1 , we mentioned that OS-9 has a unified I/O system, 
consisting of all modules except those on the kernel level. This 
chapter discusses the I/O modules in detail. 

I/O System Modules 





lOMAN 
































RBI MAN 

Disk 
File Mgr. 




SCTMAN 

Char. 
Hie Mgr. 




PIPFMAN 
Pipe 

Hie Mgr. 






































1 


CCDISK 
Disk 
Driver 




mo 

Video' 
Keybd. 
Driver 




PRINTKR 
Printer 
Driver 




RS232 

Serial 

Port 

Driver 




PIPHS 
Dummy 
Driver 












L 




L 




\ 
























DO 




Dl 




TFRM 




P 




RS232 




PIPH 



Device Descriptors 

The I/O system provides system-wide, hardware-independent 
I/O services for user programs and OS-9 itself. All I/O system 
calls are received by the kernel and passed to lOMAN for 
processing. 
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IOMAN 



File Managers 



IOMAN performs some processing, such as the allocation of 
data structures for the I/O path. Then, it calls the file managers 
and device drivers to do most of the work. Additional file 
manager, device driver, and device descriptor modules can be 
loaded into memory from files and used while the system is 
running. 



IOMAN provides the first level of service of I/O system calls. It 
routes data on I/O process paths to or from the appropriate file 
managers and device drivers. 

IOMAN also maintains two important internal OS-9 data struc- 
tures—the "device table' ' and the "path table/' Never modify 
IOMAN. 

When a path is opened, IOMAN tries to link to a memory 
module that has the device name given or implied in the pathlist. 
This module is the device descriptor. It contains the names of 
the device driver and file manager for the device. IOMAN saves 
the names so later system calls can be routed to these modules. 



OS-9 can have any number of file manager modules. Each of 
these modules processes the raw data stream to or from a class of 
device drivers that have similar operational characteristics. It 
removes as many unique characteristics as possible from I/O 
operations. Thus, it assures that similar devices conform to the 
OS-9 standard I/O and file structure. 

The file manager also is responsible for mass storage allocation 
and directory processing, if these are applicable to the class of 
devices it served. 
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File managers usually buffer the data stream and issue requests 
to the kernel for dynamie allocation of buffer memory. They 
may also monitor and process the data stream, for example, 
adding line-feed characters after carriage-return characters. 

The file managers are reentrant. The two standard OS-9 file 
managers are: 

• Random Block File Manager (RBFMAN) — supports 
random-access, block-structured devices such as disk 
systems and bubble memories. (Chapter 5 discusses 
RBFMAN in detail.) 

• Sequential Character File Manager (SCFMAN) — sup- 
ports single-character-oriented devices, such as CRT 
or hardcopy terminals, printers, and modems. {Chap- 
ter 6 discusses SCFMAN in detail.) 



Device Driver Modules 



The device driver modules are subroutine packages that perform 
basic, low- level I/O transfers to or from a specific type of I/O 
device hardware controller. These modules are reentrant so one 
copy of the module can run at the same time several devices that 
use identical I/O controllers. 

Device driver modules use a standard module header, in which 
the module type is specified as code $0E (device driver). The 
execution offset address in the module header points to a branch 
table that has a minimum of six 3-byte entries. 
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Each entry is typically a LBRA to the corresponding subroutine. 
The file managers call specific routines in the device driver 
through this table, passing a pointer to a path descriptor and the 
hardware control register address in the 6809 register. The 
branch table looks like this: 

Code Meaning 

-f $00 Device initialization routine 

4 $03 Read from device 

+ $06 Write to device 

+ $09 Get device status 

+ $0C Set device status 

+ $0F Device termination routine 

(For a complete description of the parameters passed to these 
subroutines, see the ''Device Driver Subroutines" sections in 
Chapters 5 and 6.) 



Device Descriptor Modules 



Device descriptor modules are small, non-executable modules. 
They provide information that associates a specific I/O device 
with its logical name, hardware controller address(es), device 
driver, file manager name, and initialization parameters. 

Unlike the device drivers and file managers — which operate on 
classes of devices — each device descriptor tailors its functions 
to a specific device. Each device must have a device descriptor. 

Device descriptor modules use a standard module header, in 
which the module type is specified as code $0F (device descrip- 
tor). The name of the module is the name by which the system 
and user know the device (the device name given in pathlists). 
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The rest of the 
tion in the foil 

Relative 
Address(es) 



device descriptor header consists of the informa- 
owing chart: 

Use 



$09, $0 A 
$0B,$0C 

SOD 

0E$,$()F,$1() 

$11 

$12, $12 + // 



File manager name string relative 
address 

Device driver name string relative 
address 

Mode/Capabilities: D S PE PW PR 
E W R (directory, sharable, public 
execute, public write, public read, 
execute, write, read) 

Device controller absolute physical 
(24-bit) address 

Number of bytes in bytes) in the 
intiali/ation table) 

Initialization table 



When a path to the device is opened, the initialization table is 
copied into the "option section" (PD.OPT) of the path descrip- 
tor. (See "Path Descriptors" in this chapter.) 

The values in this table may be used to define the operating 
parameters that are changeable by the Get Status and Set Status 
system calls (I$getstt and iSsetstt). For example, a terminal's 
initialization parameters define which control characters are 
used for such functions as backspace and delete. 

The initialization table may be up to 32 bytes long. If the table is 
less than 32 bytes long, the remaining values in the path descrip- 
tor are set to 0. 

You may wish to add devices to your system. If a similar device 
controller already exists, all you need to do is add the new 
hardware and load another device descriptor. Device descrip- 
tors can be in ROM or loaded into RAM from mass-storage files 
while the system is running. 

The diagram on the next page illustrates the device descriptor 
format: 
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Device Descriptor Format 



Use 



Relative 
Address 

$00 
$01 

$02 
$03 
$04 
$05 
$06 

$07 
$08 
$09 
$0A 
SOB 

$0D 

$0E 
$0F 
$10 

$11 

$12, 12-f// 



S\nc Bytes ($X7CD) 



Modulo Si/c 



Offset to Module Name 



$1 ; (Type) $1 (Lang) 



Attributes 



Revision 



Header Parity Check 



Offset to File Manager 
Name String 



Offset to Device Driver 
Name String 



Mode Byte 



Device Controller 

Absolute Physical Addr. 

(24 bit) 



Initialization Table Size 



(Initialization Table) 



(Name Strinns, and so on) 



CRC Cheek Value 



Check 
Range 



header 

parity 



module 
CRC 
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Path Descriptors 



Every open path is represented by a data structure called a path 
descriptor (PD). It contains the information the file managers 
and device drivers require to perform I/O functions. 

PDs are 64 bytes long and are dynamically allocated and deallo- 
cated by I OMAN as paths are opened and closed. 

They are internal data structures, which are not normally refer- 
enced from user or applications programs. The description of 
PDs is presented here mainly for those programmers who need 
to write custom file managers, device drivers, or other exten- 
sions to OS -9. 

PDs have three sections. The first 10-byte section is the same for 
all file managers and device drivers, as shown in the chart on the 
next page: 



Path Descriptor: Standard Information 



Name 



Relative 
Address 



Size 
(Bytes) 



Use 



PD.PD $00 

PD.MOI) $01 



PD.CNT 



PD.DPV 



$02 



$03 



Path number 

Access mode: I _ read, 2 - write, 
3 — update 

Number of open images (paths using 
this PO) 

Address of the associated device table 
entry 



pn.cpR 


$05 


PD.RGS 


$06 


PD.BUF 


$08 



Current process II) 

Address of the caller's register stack 

Address of the 256-byte data buffer 

(if used) 



31 



PD.KST $0A 22 Dctinctl h> the file manuger 

PIXOPT S20 32 Reserved for the Getstat- Selstat 

options 

PD.FST is reserved for and defined by each type of file man- 
ager for file pointers, permanent variables, and so on. 

PI). OPT is used as an option area for file or device operating 
parameters that are dynamically alterable. When the path is 
opened, IONIAN initializes these variables by copying the in- 
itialization table that is in the device descriptor module. User 
programs can change them later, using the Get Status and Set 
Status system calls. 

PD.FST and PD.OPT are defined tor the file manager in the 
assembly- language equate file (SCFDefs for SCFMAN and 
RBFDefs for RBFMAN). 
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5/ Random Block File Manager 



The Random Block File Manager (RBFMAN) supports disk 
storage. 1 1 is a reentrant subroutine package called by I OMAN 
for I/O system calls to random-access devices. It maintains the 
logical and physical file structures. 

During normal operation. RBFMAN requests allocation and 
deallocation of 256-byte data buffers. Usually, one is required 
for each open file. When physical I/O functions are necessary, 
RBFMAN directly calls the subroutines in the associated device 
drivers. All data transfers are performed using 256-byte data 
blocks (pages). 

RBFMAN docs not deal directly with physical addresses such as 
tracks and cylinders. Instead, it passes to the device drivers 
address parameters, using a standard address called a 'logical 
sector number", or "LSN/ 1 LSNs are integers from to //-/, 
where n is the maximum number of sectors on the media. The 
driver translates the logical sector number to actual cylinder/ 
track/sector values. 

Because RBFMAN supports many devices that have different 
performance and storage capacities, it is highly parameter- 
driven. The physical parameters it uses are stored on the media 
itself. 

On disk systems, this information is written on the first few 
sectors of Track 0. The device drivers also use this information, 
particularly the physical parameters stored on Sector 0. These 
parameters are written by the Format program that initializes 
and tests the media. 
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Logical and Physical Disk Organization 



All disks used by OS-9 use the first few sectors to store basic 
identification, file structure, and storage allocation information. 

LSN is the "identification sector/ " LSN 1 is the "disk 
allocation map sector/' LSN 2 marks the beginning of the 
disk's root directory. The following section tells more about 
LSN and LSN 1. 



Disk Sectors 



Identification Sector (LSN 0) 



LSN contains a description of the physical and logical charac- 
teristics of the disk. These characteristics are set by the Format 
command program when the disk is initialized. 

The table below gives the OS-9 mnemonic name, byte address, 
si/e, and description of each value stored in this LSN 0. 



Name 


Relative 


Size 


Use 




Address 


(Bytes) 




DO. TOT 


$00 


3 


Number of sectors on disk 


nn.TKS 


$03 


i 


Track si/e (in sectors) 


DD. MAP 


$04 


T 


Number of bytes in the allocation bit 
map 


DD. BIT 


$06 


"> 


Number of" sectors per cluster 


DD.DIR 


$08 


3 


Starting sector of the root directory 


DD.OWN 


$0B 


2 


Owner's user number 


DD.ATT 


$01) 


1 


Disk attributes 


DD.DSK 


$0h 


"j 


Disk identification (Tor internal use) 


DD.FMT 


$10 


1 


Disk format, density, number of sides 


DD.SPT 


$11 


2 


Number of sectors per track 


DD.RHS 


$13 


2 


Reserved for future use 


DD.BT 


$15 


3 


Starting sector of the bootstrap file 


DD.BSZ 


$18 


2 


Si/e of the bootstrap file (in bytes) 


DD.DAT 


$IA 


5 


Time of creation: Y:M:D:H:M 


DD. NAM 


$IF 


32 


Volume name: last character has the 
most significant bit set 
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Disk Allocation Map Sector (LSN 1) 



LSN 1 contains the ''disk allocation map," which is created by 
Format. This map specifics which sector clusters are available 
for file allocation. 

The DD.MAP value in LSN specifies the number of bytes (in 
LSN 1) that are used in the map. 

Each bit on the map corresponds to one sector cluster on the 
disk. The DD. BIT value in LSN specifies the number of 
sectors per cluster. The number is an integral power of 2 (1,2, 
4, 8, 16, and so on). The map may contain up to 4096 bits. 
Therefore, hard disks and double-density, doublcd-sided disk- 
ettes have two or more sectors per cluster. 

If a cluster is available, the corresponding bit is cleared. If it is 
allocated, non-existent, or physically defective, the correspond- 
ing bit is set. 



File Sectors 



File Descriptor Sector 



The first sector of every file is the 'Tile descriptor/ 1 It contains 
the logical and physical description of the file. 

The table below describes the contents of the file descriptor. 



Name 


Relative 


Size 


Use 




Address 


(Bytes) 




FD.ATT 


$00 


1 


File attributes: D S PF PW PR F W R 

(sec below) 


FD.OWN 


$01 


T 


Owner's user ID 


ID. DAT 


$03 


s 


Dale last modified: Y M D H M 


FS.FNK 


SOS 


1 


Fink count 


FD.SIZ 


$09 


4 


File si/e (number of bytes) 


FD.IX'R 


SOD 


3 


Date created: Y M D 


FD.SFC. 


$10 


240 


Segment list (see below) 
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FD.ATT (the attribute byte) contains the file permission bits. 
When set the bits indicate the following 



Bit 7 


Directory 


Bit 6 


Sharable 


Bit 5 


Public execute 


Bit 4 


Public write 


Bit 3 


Public read 


Bit 2 


Execute 


Bit 1 


Write 


Bit 


Read 



FD.SEG (the segment list) consists of up to 48 5-byte entries 
that have the size and address of each file block in logical order. 
Each entry has the block's 3-byte LSN and 2-byte size (in 
sectors). The entry following the last segment will be zero. 

After creation, a file has no data segments allocated to it until 
the first write. (Write operations past the current end-of-file 
cause sectors to be added to the file. The first write is always 
past the end-of-file.) 

If the file has no segments, it is given an initial segment. 
Usually, this segment has the number of sectors specified by the 
minimum allocation entry in the device descriptor. If, however, 
the number of sectors requested is more than the minimum, the 
initial segment has the requested number. 

Later expansions of the file usually are made in minimum 
allocation increments, also. OS-9 expands the last segment, 
whenever possible, instead of adding a segment. When the file 
is closed, unused sectors in the last segment are truncated. 

Note: OS-9 tries to minimize the number o( storage seg- 
ments used in a file. In fact, many files have only one 
segment. In such cases, no extra read operations are 
needed to randomly access any byte on the file. 

If a file is repeatedly closed, opened, and expanded, it 
may become fragmented and may have many segments. 
You can avoid this problem by writing a byte at the 
highest address to be used on a file. Do this before writing 
anv other data. 
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Directories 



"Disk directories" are files that have the D attribute set. A 
directory contains an integral number of entries, each of which 
can hold the name and LSN of a file or another directory. 

Each directory entry contains 29 bytes for the filename, fol- 
lowed by the 3-byte LSN of the file's descriptor sector. The 
filename is left-justified in the field with the sign bit of the last 
character set. Unused entries have a zero byte in the first 
filename character position. 

Every disk has a master directory called the "root directory/ 1 
The DD.DIR value in LSN (identification sector) specifies the 
starting sector of the root directory. 



RBFMAN Definitions of the Path Descriptor 



As stated earlier in this chapter, the PD.FST section of the path 
descriptor is reserved for and defined by the file manager. The 
table below describes the use of this section by RBFMAN. For 
your convenience, it also includes the other sections of the PD. 



Name 


Relative 


Size 


Use 




Address 


(Bytes) 




Universal 


Section (Same 


for till file managers and device drivers) 


PD.PD 


$00 


1 


Path number 


PD.MOD 


$01 


1 


Access mode: 1 - read. 2 = write, 
3 = update 


PD.CNT 


$02 


1 


Number of open images (paths using 
this PD) 


PD.DHV 


$03 


i 


Address of the associated device table 
entrv 


PD.CPR 


$05 


1 


Current process ID 


PD.RGS 


$06 


2 


Address of (he caller's 6809 register 
stack 


PD.BUF 


$08 


2 


Address of the 256-bytc data buffer (if 
used) 
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Name Relative Size Use 
Address (Bytes) 



RBFMAN Path Decnptor Definitions (PD.FST Section) 

PD.SMF $0A I State flag: = current buffer is 

altered, I — current sector is in the 
buffer, 2 = descriptor sector is in the 
buffer 

PD.CP $0B 4 Current logical file position (byte 

address) 

PD.SIZ $0F 4 File size 

PD.SBL $13 3 Segment beginning logical sector 

number (LSN) 

PD.SBP $16 3 Segment beginning physical sector 

number (PSN) 



PD.SSZ 


$19 


PD.DSK 


$IB 


PD.DTB 


$1D 



Segment size 

Disk ID (for internal use only) 

Address of drive table 



RBFMAN Option Section Definitions (PD.OPT Section) 
(Copied from the device descriptor) 





$20 


1 


Device class: - SCF, 1 - RBF, 
2 = PIPE, 3 - SBF 


PD.DRV 


$21 


1 


Drive number (0 . . n) 


PD.STP 


$22 


1 


Step rate 


PD.TYP 


$23 


1 


Device type 


PD.DNS 


$24 


1 


Density capability 


PD.CYL 


$25 


2 


Number of cylinders (tracks) 


PD.SID 


$27 


1 


Number of sides (surfaces) 


PD.VFY 


$28 


1 


= verify disk writes 


PD.SCT 


$29 


2 


Default number of sectors per track 


PD.TOS 


$2B 


2 


Default number of sectors per track 
(Track 0) 


PD.ILV 


$2D 


1 


Sector interleave factor 


PD.SAS 


$2E 


1 


Segment allocation size 


(Not copied 


from the device 


descriptor) 


PD.ATT 


$33 


1 


File attributes (D S PE PW PR E W R) 


PD.FD 


$34 


3 


File descriptor PSN 


PD.DFD 


$37 


3 


Directory file descriptor PSN 


PD.DCP 


$3A 


4 


File's directory entry pointer 


PS. DVT 


$3E 


2 


Address of the device table entry 



Any values not determined by this table default to zero. 
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RBF-Type Device Descriptor Modules 



This section describes the use of the initialization table con- 
tained in the device descriptor modules for RBF-type devices. 
The values below are those IOMAN copies from the device 
descriptor to the path descriptor. 



Name 


Relative 


Size 


Use 




Address 


(Bytes) 






$0-SH 




Standard device descriptor module 
header 


IT. DIP 


$12 


1 


Device type: - SCI\ 1 - RBK 
2 - pipi;. 3 - SBI 


IT. DRV 


$13 


1 


Drive number (see below) 


1T.STP 


$14 


1 


Step rate (see below) 


1T.TYP 


$15 


1 


Device type (see below) 


IT. DNS 


$16 


1 


Media density: = single, 1 -- dou- 
ble (see below) 


IT.CYL 


$17 


2 


Number of cylinders (tracks) 


IT. SID 


$19 


1 


Number of sides 


IT.VIT 


$1A 


1 


- Verify disk writes 


IT.SCT 


$1B 


T 


Default number of sectors per track 


IT.TOS 


$ID 


T 


Default number of sectors per track 
(Track 0) 


IT.ILV 


$1F 


1 


Sector interleave factor 


IT.SAS 


$20 


1 


Minimum si/e of segment allocation 
(number of sectors to be allocated at 
one time) 



IT. DRV is used to associate a 1 -byte integer with each drive 
that a controller handles. The drives tor each controller should 
he numbered to//-/, where n is the maximum number of drives 
the controller can handle. 

IT.STP (floppy disks) sets the head stepping rate to be used 
with a drive. To reduce access time, this should be the fastest 
rate the drive can support. The actual values stored depend on 
the specific disk controller and disk driver module used. Below 
are the values that are used by the popular Western Digital 
Floppy Disk Controller IC (FD179X 5-Inch): 
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Step Code Rate 






1 








30ms 
20ms 




2 








1 2ms 




3 








6 ms 


IT 


.TYP speci 


fies 


the 


de 


vice type (all types) 




Bit — 





1 


— 


5- inch floppy disk 
8-inch floppy disk 



Bit 5 — = Non-Color Computer format 

1 = Color Computer format 

Bit 6 — - Standard OS-9 format 

1 = Non-standard format 

Bit 7 — - () = Floppy disk 

1 = Hard disk 

IT. DNS specifies the density capabilities {floppy disk only). 

Bit — () = Single-bit density (FM) 

1 = Double-bit density (MFM) 

Bit I — () = Single-track density (5-inch, 48 

tracks per inch) 
1 = Double-track density (5-inch, % 
tracks per inch) 



RBF-Type Device Driver Modules 



An RBF-type device driver module contains a package of sub- 
routines that perform sector-oriented I/O to or from a specific 
hardware controller. These modules are usually reentrant. Be- 
cause of this, one copy of the module can simultaneously run 
several devices that use identical I/O controllers. 
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IONIAN allocates a permanent memory area for each device 
(which may control several drives). The size of the memory area 
is given in the device driver module header. IOMAN and 
RBFMAN use some of this area. The device driver may use the 
rest in any manner. This area is used as follows: 



RBF Device Memory Area Definitions 



Name 


Relative 


Size 


Use 




Address 


(Bytes) 




V.PAC.R 


$00 


1 


Port extended address 24 " blt 

(A20 -A 16) dL jV Ce 
address 


V.PORT 


SOI 


2 


Device base address (defined 

by (OMAN) 


V.LPRC 


$03 


1 


ID of the last active process (Not used 
by RBF device drivers) 


V.BUSY 


$04 


1 


ID of the active process; — not busy 
(defined by RBFMAN) 


V.WAKF 


$05 


1 


ID of the process to reawaken after 
device completes I/O; — no process 
waiting (defined by device driver) 


V.USFR 






Rnd of the OS-9 definitions 


V.NDRV 


$06 


1 


Number of drives the controller can 
use (defined by the device driver) 


DRVBFG 






Beginning of the drive tables 


TABFHS 


S07 


DRVMFN :f 


: N Number of tables reserved (/;) 


FRFF 






Free for the driver to use 



V.PAGE through V.USER are pre-defined in the OS-9Defs 
file. V.NDRV, DRVBEG, DRVMEN are pre-defined in the 
RBFDefs file. 

TABLES. This area contains one tahle for each drive that the 
controller will handle. (RBFMAN assumes that there are as 
many tables as indicated by V.NDRV). Some time after the 
driver I nit routine has been called, RBFMAN issues a request 
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for the driver to read LSN (the identification sector) from a 
drive table by copying the first part of LSN (up to DD.SIZ) 
into it. 

The format of each drive tabic is as given below: 

Name Relative Size Use 

Address (Bytes) 



DO. TOT $00 

DD.TKS $03 

DO. MAP $04 



DD.B1T 



$06 



DD.D1R 


SOS 


DD.OWN 


$0B 


DD.ATT 


SOI) 


DD.DSK 


sop; 


DD.FMT 


S10 


DD.SPT 


$n 



DD.RBS $15 

DD.SIZ 

V.TRAK SPS 

V.BMB $17 

DRVMEN $18 



Number of sectors. 

Track size (in sectors). 

Number of bytes in the allocation 
bit map. 

Number of sectors per bit (cluster 
si/e). 

Address (LSN) of the root directory. 

Owner's user number. 

Disk access attributes: D S PP PW PR 
K W R. 

Disk ID (a pseudo-random number 
used to detect disk swaps). 

Media format. 

Number n\' sectors per track. (Track 
may use a different value, specified 
by ITTOS in the device descriptor.) 

Reserved for future use. 



Number of the current track (the track 
(he head is on — the one updated by 
the driver). 

Bit-map use flag: = the bit map is 
not in use. (Disk driver routines must 
not alter V.BMB.) 

Si/e of each drive table. 
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The format attributes (DD.FMT) are these; 
Bit BO = Number of sides 

= Single-sided 

1 = Double-sided 

Bit Bl - Density 

= Single-density 

1 = Double-density 

Bit B2 = Track density 

= Single (48 tracks per inch) 
91 = Double (96 tracks per inch) 



RBFMAN Device Driver Subroutines 



Like all device driver modules, RBFMAN device drivers use a 
standard executable memory module format. In the header, the 
type is specified as code $0E (device driver). 

The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Each entry is typically a 
long branch (LBRA) to the corresponding subroutine. The 
branch table is defined as follows; 



ENTRY 



LBRA 


IN1T 


Initialize drive 


LBRA 


READ 


Read sector 


LBRA 


WRITE 


Write sector 


LBRA 


GETSTA 


Get status 


LBRA 


SETSTA 


Set status 


LBRA 


TERM 


Terminate device 



Each subroutine should exist with the C bit of the Condition 
Code Register cleared if no error occurred. If an error occurred, 
the C bit should be set and an appropriate error code returned in 
Register B. 

The rest of this chapter describes these subroutines and their 
entry and exit conditions. 
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Init 



Function: 

Initialize the device and its memory area. 
Entrv Conditions: 



u 


address of 


Y 


address of 


Exit Conditions; 




None 




If error: 




CC 


C bit set 


B 


error code 



Technical Function: 

1. If the disk writes are verified, use the Request 
Memory system call (F$srqmem) to allocate a 256- 
byte buffer area where a sector may be read back 
and verified after a write. 

2. Initialize the device memory area. For floppy disk 
controllers this typically consists of: 

• Initializing V.NDRV to the number of drives 
with which the controller will work 

• Initializing DD.TOT (in the drive table) to a 
non-zero value so that Sector may be read or 
written. 

• Initializing V.TRAK to $FF so that the first seek 
finds Track 0. 

3. Place the IRQ service routine on the IRQ polling 
list, using the Set IRQ system call (F$irq). 

4. Initialize the device control registers (enable 
interrupts if necessary). 
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Read 



Prior to being called, the device memory area is cleared (set to 
zero), except for V.PAGE and V.PORT. (These contain the 
24-bit device address.) The driver should initialize each drive 
table appropriately for the type of disk the driver expects to use 
on the corresponding drive. 



Copy V.BUSY to V.WAKE, then go to sleep and 
wait for the I/O to complete. (The IRQ service 
routine is responsible for sending a wakeup signal, ) 
After awakening, the driver tests V.WAKE to see if 
it is clear. If it isn't clear, the driver goes back to 
sleep. 



Function: 

Terminates a device. This routine is called when a device is 
no longer in use in the system (when the link count of its 
device descriptor module becomes zero). 



Function: 

Read a 256-byte sector from the disk and place it in the 256-byte 
buffer. 

Entry Conditions: 

U = address of the device memory area 

Y = address of the path descriptor 

B = MSB of the disk LSN 

X = LSBs of the disk LSN 

Exit Conditions: 

The sector is returned in the sector buffer. 

If error: 

CC - C bit set 

B = error code 
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Technical Function: 

1. Get the sector buffer address from PD.BUF in the 
path descriptor. 

2. Get the drive number from PD.DRV in the path 
descriptor. 

3. Compute the physical disk address from the logical 
sector number. 

4. Initiate the read operation. 

5. Copy V.BUSY to V.WAKE, then go to sleep and 
wait for the I/O to complete. (The IRQ service 
routine is responsible for sending a wakeup signal.) 
After awakening, the driver tests V.WAKE to see if 
it is clear, if it isn't clear, the driver goes back to 
sleep. 

Whenever LSN is read, the first part of this sector must be 
copied into the proper drive table. (Get the drive number from 
PD.DRV in the path descriptor.) The number of bytes to copy is 
in DD. SIZ. 

The drive number (PD.DRV) should be used to compute the 
offset to the corresponding drive table as follows: 

LDA PD.DRV.Y Get the drive number 

LDB #DRVMLiN Get the si/e of a drive tahle 

MUL 

LEAX I)RVRILG,U Get the address of the first table 

LEAX D,X Compute the address of Table n 
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Write 



Function: 

Write a 256-byte sector buffer to the disk. 

Entry Conditions: 

U = address of the device memory area 

Y = address of the path descriptor 

B = MSB of the disk LSN 

X = LSBsofthe disk LSN 

Exit Conditions: 

The sector buffer is written out to the disk. 

If error: 

CC - C bit set 

B = error code 

Technical Function: 

1 . Get the sector buffer address from PD.BUF in the 
path descriptor. 

2. Get the drive number from PD.DRV in the path 
descriptor. 

3. Compute the physical disk address from the logical 
sector number. 

4. Initiate the write operation. 

5. Copy V.BUSY lo V.WAKH, then go to sleep and 
wait for the I/O to complete. (The IRQ service 
routine is responsible for sending the wakeup sig- 
nal.) After awakening, the driver tests V.WAKKto 
see if it is clear. If it is not, the driver goes back to 
sleep. If the disk controller cannot be interrupt- 
d riven, it is necessary to perform a programmed I/O 
transfer. 



47 



Getsta 
Setsta 



6. If PF. VFY in the path descriptor is equal to zero, 
read the sector back in and verify that it was written 
correctly. This usually does not involve a compari- 
son of the data. 

If disk writes are to be verified, the Init routine must request the 
buffer where the sector may be placed when it is read back in. 
Do not copy LSN into the drive table when it is read back to be 
verified. 

Use the drive number (PL). DRV) to compute the offset to the 
corresponding drive table as shown for the Read routine. 



Function: 

Get/set the device's operating parameters (status) as specified 
for the Get Status and Set Status system calls. Getsta and Setsta 
are wildcard calls. 

Entry Conditions: 

U — address of the device memory area 

Y = address of the path descriptor 

A - status code 

Exit Conditions: 

Depend upon the function code 

If error; 

CC = C bit set 

B = error code 

It may be necessary to examine or change the register stack that 
contains the values of the 6809 register at the time of the call. 
The address of the register stack is in PD.RGS, which is located 
in the path descriptor. 



48 



Term 



The following offsets may be used to access any value in the 
register stack: 



Name 


Relative 


Size 


6809 Register 




Address 


(Bytes) 




R$CC 


soo 


1 


Condition Code Register 


RSD 


$01 




Register I) 


R$A 


$01 


1 


Register A 


R$B 


$02 


1 


Register B 


RSDP 


$03 


1 


Register DP 


RSX 


$04 


2 


Register X 


RSY 


$06 


2 


Register Y 


R$U 


$08 


T 


Register U 


R$PC 


$0A 


1 


Program Counter 



Function: 

Terminate a device. This routine is called when a device is no 
longer in use in the system (when the link count of its device 
descriptor module becomes zero). 

Entry Conditions: 

U = address of the device memory area 

Exit Conditions: 

None 



If error: 




CC 


= C bit set 


B 


— er r r code 
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Technical Function: 

1. Wait until any pending I/O is completed. 

2. Disable the device interrupts. 

3. Remove the device from the IRQ polling list. 

4. If the I nit routine reserved a 256-byte butler for 
verifying disk writes, return the memory with the 
Return Sysmem system call (FSsrtmem). 



IRQ Service Routine 



This routine is not included in the device driver's branch table 
and is not called directly by RBFMAN, but it is a key routine in 
interrupt-driven device drivers. 

The IRQ service routine services interrupts and, when I/O is 
complete, sends a wakeup signal to the process whose process 
ID is in V.WAKE. It also clears V.WAKE as a Hag to the 
mainline program that the IRQ has indeed occurred. 

When it finishes servicing an interrupt, the routine must clear 
the carry and exit with an RTS instruction. 

Technical Function: 

1. Service the device interrupts (receive data from 
device or send data to it). This routine should put its 
data into and get its data from buffers which are 
defined in the device memory area. 

2. Wake up any process that is waiting for I/O to 
complete. To do this, it checks to see if there is a 
process ID in V.WAKE (non-zero); if so, it sends a 
wakeup signal to that process. 

3. If the device is ready to send more data and the 
output buffer is empty, disable the device's kt ready 
to transmit" interrupts. 
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If a pause character is received, set V.PAUS in the 
attached device storage area to a no n -zero value. 
The address of the attached device memory area is 
in V.DKV2. 



Boot (Bootstrap Module) 



Function: 

Load the Boot file into memory from mass-storage. 

Entry Conditions: 

None 

Exit Conditions: 

D = size of the hoot file (in bytes) 

X = address where the hoot file was loaded into 

memory 

If error: 

CC = C hit set 

B = error eode 

The Boot module is not part of the disk driver. It is a separate 
module which is normally co-resident with the OS9P2 module 
in the system firmware. 

The bootstrap module contains one subroutine that loads the 
bootstrap file and some related information into memory. It uses 
the standard executable module format with a module type of 
"system" (code $C). The execution offset in the module header 
contains the offset lo the entry point of this subroutine. 

It obtains the starting sector number and size ofthe()S9Boot file 
from LSN 0. OS -9 is called to allocate a memory area large 
enough for the Boot file, and then it loads the Boot file into this 
memory area. 
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Technical Function: 



i 



Read LSN from the disk into a buffer area. Boot 
must pick its own buffer area, LSN contains the 
values for DD.BT (the 24-bit LSN of the bootstrap 
file), and DD. BSZ (the si/e of the bootstrap file in 
bytes). 

Get the 24-bit LSN of the bootstrap file from 
DD.BT. 



3. Get the size of the bootstrap file from DD. BSZ. The 
Boot is contained in one logically contiguous block 
beginning at the logical sector specified in DD.BT 

. and extending for (DD.BSZ/256 + 1) sectors. 

4. Use the OS-9 Request Sysmem system call 
(FSsrqmem) to request the memory area where the 
Boot file will be loaded. 

5. Read the Boot file into this memory area, 

6. Return the size of the Boot file and its location. 
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6 / Sequential Character File 
Manager 



The Sequential Character File Manager (SCFMAN) supports 
devices that operate on a character-by-character basis. These 
include terminals, printers, and modems. 

It is a reentrant subroutine package called by lOMAN for I/O 
system calls to sequential, character-oriented devices. It in- 
cludes the extensive I/O editing functions typical of line- 
oriented operation (backspace, line delete, repeat line, auto line 
feed, screen pause, and return delay padding). 

OS-9 is supplied with SCFMAN and one SCR-type device 
driver module. The module is an RS-232-type, which runs the 
serial interface. 



SCFMAN Line Editing Functions 

Read and Write 

The Read and Write system calls (iSread and 1$ write) to 
SCFMAN-type devices correspond to the BAS1C09 OFT and 
PUT statements. They pass data to/ from the device with little 
modification. 

Note: Although there is otherwise little modification, the 
keyboard interrupt, keyboard abort, and pause character 
are filtered out of the input. (Editing is disabled if the 
corresponding character in the path descriptor contains a 
zero.) 

Carriage returns are not followed by line feeds or nulls auto- 
matically, and the high order bits are passed as sent/received. 

Read Line and Write Line 

The Read Line and Write Line system calls (ISreadln and 
I$writln) to SCFMAN devices correspond to the BASIC09 
INPUT, PRINT. READ, and WRITK statements. They perform 
full line editing of all functions enabled for the particular device. 
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These functions are initialized when the device is first used. 
(The option tahle is copied from the device descriptor table 
associated with the specific device.) 

Later, they may be altered — either from assembly-language 
programs using the Get Status system call, or from the keyboard 
using the Tmode command. All bytes transferred in this mode 
will have the high order bit cleared. 



SCFMAN Definitions of the Path Descriptor 



As you know, the PD.FST and PD.OPT sections of the path 
descriptor are reserved for and used by the file manager. 

The table below describes the use of PD.FST and PD.OPT by 
SCFMAN. For your convenience, it also includes the other 
sections of the PD. 

The PD.OPT section contains the values that determine the line 
editing functions. It contains many device operating parameters 
which may be read or written by the Set Status or Get Status 
system call. Any values not set by this table default to zero. 

Note: It is possible to disable most of the editing functions 
by setting the corresponding control character in the path 
descriptor to zero. You can use the Set Status system call 
or the Tmode command to do this. Or, you may go a step 
further by setting the corresponding control character 
value in the device descriptor module to zero. 

To determine the default settings for specific devices, you may 
inspect the device descriptors. 

Name Relative Size Use 

Address (Bytes) 

Universal Section (Same lor all file managers) 

PD.PD $00 1 Path number 

1 Access mode: 1 = read, 2 write, 

3 = update 

1 Number of open images (paths using 
this PD) 

2 Address of the associated device table 
entry 

1 Current process ID 



PD.MOD 


$01 


PD.CNT 


$02 


PD.DPV 


$03 


PD.CPR 


$05 
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PD.RGS 
PD.BUF 



$06 
SOS 



Address of the caller's 6809 register 
stack 

Address of the 256-byte data buffer (if 
used) 



SCFMAN Path Descriptor Definitions (PD.FST Section) 



PD.DV2 

PD.RAW 

PD.MAX 
PD.MIN 
PD.STS 
PD.STM 



SOA 
$()C 

SOD 

$0F 
$10 
$12 



Device tabic address of the second 

( echo )de vice 

Edit flag: = raw mode, 1 = edit 

mode 

Read Line maximum character count 
Devices are "mine" if cleared 
Status routine module address 
Reserved tor status routine 



Name 



Relative 

Address 



Size Use 
(Bytes) 



SCFMAN Option Section Definition (PI). OPT Section) 

(Copied from the device descriptor) 

$20 1 Device class: = SCF, 1 - RBF. 

2 = P1PF, 3 - SBF 

1 Case: = upper and lower, 

1 — upper only 

1 Backspace: _ backspace, 

1 = backspace then space and back- 
space 

1 Delete: -- backspace over line, 

1 — carriage re turn/ line feed 



PD.L'PC 
PD.BSO 

PD.DLO 

PD.FKO 
PD.ALF 

PI). NIL 
PD.PAU 



$21 

$22 

$23 

$24 
$25 

$26 
S27 



PD.PACJ 


$28 


PD.BSP 


$2 e ) 


PI). DEL 


,$2A 


PD.FOR 


S2B 



Echo: = no echo 

Auto line feed after carriage return: 
= no auto line feed 

End-of-linc null count: 1 - nulls 

($00) sent after each carriage return/ 
line feed 

Number of lines (since last input) be- 
fore each end-of-page pause: - no 
pause 

Lines per page 

Backspace character 

Delete-! ine character 

Fnd-of- record character (end-of-line 
character) read only: Normally set to 
SOD: = Terminate Read Line only 
at the end of (he file 
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PD.DUP 


%2\- 


PD.PSC 


$2b 


PI). INT 


$30 


PD.QLT 


S3I 


pd.bsk 


%M 


PD.OVf- 


$33 


PI). PAR 


$34 


PD.BAU 


S3.S 


PD.D2P 


$36 


PD.STN 


$38 


PD.LRR 


$3 A 



PD.hOF $2C I Lnd-of-file character (read only) 

PI), RPR $21) 1 Reprint-line character 

Name Relative Size Use 

Address (Bytes) 

1 Duplicate-last-line character 

1 Pause character 

I Keyboard- interrupt character (CLEAR) 

1 Keyboard-abort character (CLEAR) CJD 

1 Backspace-echo character 

I Line-overflow character (bell) 

I Device- initialization value (parity) 

1 Software settable baud rate 

2 Offset to second device name string 
2 Offset o\ status routine name 

I Most recent I/O error status 

PL). EOF specifics the end-of-file character. If this is the first 
and only character input, SCFMAN returns an end-of-file error 
on Read or Readln. 

PD.PSC specifies the pause character, which suspends output 
before the next end-of-record character. The pause character 
also deletes any type-ahead input for Readln. 

PD.INT specifies the keyboard-interrupt character. When the 
character is received on input, a keyboard interrupt signal is sent 
to the last user of this path. The character also terminates the 
current I/O request (if any) with an error identical to the 
keyboard interrupt signal code. 

PD.QUT specifies the key board- abort character. When this 
character is received on input, a keyboard abort signal is sent to 
the last user of this path. It also terminates the current I/O 
request (if any) with an error code identical to the keyboard 
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SCF-Type Device Descriptor Modules 



The chart helow shows the use of the initialization table in the 
device descriptors for SCF-type devices. The values are those 
IOMAN copies from the device descriptor to the path 
descriptor. 

An SCF editing function is turned off if its corresponding value 
is set to zero. For example, if IT.HOF is set to zero, there is no 
end-of-file character. 

Use 



Beginning of the option table 

Device das*: - SCF, 1 - RBI . 
2 - PIPH, 3 = SCT 

Case: = upper and lower case, 
1 - upper only 

Backspace: - backspace; 
1 - backspace then space and back- 
space 

IT.DLO SLS 1 Delete: - backspace over line. 

1 - carriage return 



Name 


Relative 


Size 




Address 


(IHtes) 


TABLK 






IT.DVC 


$12 


1 


IT. UPC 


$13 


1 


IT.BSO 


$14 


1 



IT.KKO 


$16 


1 


Hcho: t) - no echo 


1T.ALF 


S17 


1 


Auto line iced: = no auto line iced 


Name 


Relative 


Size 


Use 




Address 


(Bytes) 




IT.NUL 


SIX 


1 


Hnd-oi line null count 


IT. PAL' 


$19 


I 


Pause: - no end-of-pagc pause 


IT. PAG 


$IA 


I 


Lines per page 


1T.BSP 


$IB 


1 


Backspace character 


IT. DHL 


SIC 


1 


Delete-line character 


IT. FOR 


SID 


1 


Fnd-of-record character 


IT.HOF 


$IH 


1 


Hnd-ot'-l'ile character 


IT. RPR 


SIF 


1 


Reprint-line character 


IT.DUP 


S20 


1 


Duplicate- last- line character 


IT.PSC 


S2I 


1 


Pause character 


IT. INI 


$22 


1 


Interrupt character 


IT. OUT 


%2} 


1 


Quit character 


IT.BSH 


$24 


1 


Backspace echo character 
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IT.OVF 


S25 


IT. PAR 


%2b 


IT.BAU 


$27 


IT.D2P 


S28 


IT.STN 


$2 A 


IT.KRR 


%2V 



Line-overflow character (bell) 

Initialization value (parity) used to in- 
itialize the device's control register 
when a path is opened to it 

Baud rate 

Attached device name string offset 

Offset to status routine 

Initial error status 



SCF-Type Device Driver Modules 



A SCFMAN-type device driver module contains a package of 
subroutines that perform raw I/O transfers to or from a specific 
hardware controller. These modules are usually reentrant so that 
one copy of the module can simultaneously run several different 
devices that use identical I/O controllers. For each 'incarna- 
tion' ' of the driver, IOMAN allocates a permanent memory area 
for that device. 

The size of the memory area is given in the device driver module 
header. IOMAN and SCFMAN use some of this area. The 
device driver may use the rest in any way (typically as variables 
and buffers). The area is used as follows: 
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SFC Device Memory Area Definitions 



Name 



V.PAGE 

V.PORT 

V.LPRC 
V.BUSY 

V.WAKE 



Relative 
Address 



Size 

(Bytes) 



Use 



$00 

$01 

$0.1 
$04 

$05 



Port extended address 24 " blt 
device 

address 
Device base address (ddmed 

b> IONIAN) 
ID of the last active process 

ID of the active process; — not busy 
(defined by RBFMAN) 

ID of the process to reawaken after the 
device completes I/O: = no process 

is waiting (defined by the device 
driver) 



V.USER 




End of the OS-9 definitions 


V.TYPE 


$06 


1 Device type of parity 


V.LINE 


$07 


1 Lines left until the end of the page 


V.PAUS 


$08 


I Pause request: = no pause 


V.DEV2 


$09 


2 Attached device memory area 


V.INTR 


SOB 


1 Interrupt character 


V.QUIT 


$oc 


1 Quit character 


V.PCHR 


SOD 


1 Pause character 


V.ERR 


$0E 


1 Error accumulator 


V.SCF 


$0F 


1 End of the SCFMAN definitions 


FREE 




Free for the device driver to use 



V.LPRC contains the process-ID of the last process to use the 
device. The IRQ service routine is responsible for sending this 
process the proper signal in case a quit character or an interrupt 
character is received. V.LPRC is defined by SCFMAN. 
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V.BUSY contains the process ID of the process that is using the 
device. (If the device is not being used, V.BUSY contains a 
zero.) This is used by SCFMAN to prevent more than one 
process from using the device at the same time. V.BUSY is 
defined by SCFMAN. 



SCFMAN Device Driver Subroutines 



Init 



Like all device drivers, SCFMAN device drivers use a standard 
executable memory module format. In the header the type is 
specified as code SOF (device driver). 

The execution offset address in the module header points to a 
branch table that has six 3-byte entries. Bach entry is typically a 
LBRA to the corresponding subroutine. The branch table is 
defined as follows: 

LNTRY 



[BRA 


INIT 


Initialize drive 


[.BRA 


RKAD 


Read sector 


LBRA 


WRITH 


Write sector 


LBRA 


GHTSTA 


Gel status 


LBRA 


SL I ST A 


Set status 


LBRA 


TLRM 


Terminate devict 



Each subroutine should exist with the C bit in the Condition 
Code Register cleared if no error occurred. If an error occurred, 
the C bit should be set and an appropriate error code returned in 
Register B. 

The rest of this chapter describes these subroutines and their 
entry and exit conditions. 



Function: 

Initialize the device control registers (enable interrupts, if 
necessary). 

Entry Conditions: 

U = address of the device memory area 

Y = address of the device descriptor 
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Read 



Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 

Technical Function: 

1. Initialize the deviee memory area. 

2. Place the IRQ service routine on the IRQ polling 
list, using the Set IRQ system call (FSirq). 

3. Initialize the device control registers. 

Prior to being called, the device memory area is cleared (set to 
zero), except for V.PAGE and V.PORT. (These contain the 
device address.) There is no need to initialize the part of the 
memory area used by IONIAN and SCFMAN. 



Function: 

Read the next character from the input buffer. 

Entry Conditions: 

U = address of the device memory area 

Y — address of the path descriptor 

Exit Conditions: 

A = character read 

If error: 

CC = C bit set 

B = error code 
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Write 



Technical Function: 

1 . Get the next character from the input buffer. 

2. If no data is ready, Read copies its process ID from 
V.BUSY into V.WAKE. It then uses the Sleep 
system call to put itself to sleep. 

Later, when data is received, the Set IRQ system 
call leaves the data in a buffer, then checks 
V.WAKH to see if any process is waiting for the 
device to complete I/O. If so, Set IRQ should send a 
wakeup signal to it. 

Data buffers are not allocated automatically. If a buffer is used, 
it should be defined in the device memory area. 



Function: 

Output a character (place a data byte into an output buffer) and 
enable the device output interrupts. 

Entry Conditions: 

U — address of the device memory area 

Y — address of the path descriptor 

A = character to write 

Exit Conditions: 

None 

If error: 

CC - C bit set 

B = error code 

1. If the data buffer is already full, Write copies its 
process ID from V.BUSY into V.WAKE. It then 
puts itself to sleep. 
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Getsta 
Setsta 



2. Later, when the IRQ service routine transmits a 
character and makes room for more data, Write 
checks V.WAKE to see it there is a process waiting 
for the device to complete I/O. inhere is, it sends a 
wakeup signal to that process. 

Write must ensure that the IRQ service routine will start up 
when data is placed into the buffer. After an interrupt is gener- 
ated, the IRQ service routine continues to transmit data until the 
data buffer is empty. Then, it disables the device's "ready to 
transmit 1 ' interrupts. 

Data buffers are not automatically allocated. If a buffer is used, 
it should be defined in the device memory area. 



Function: 

Get/set the device's operating parameter (status) as specified for 
the Get Status and Set Status system calls. Getsta and Setsta are 
wildcard calls. 

Entry Conditions: 

U = address of the device memory area 

Y = address of the path descriptor 

A = status code 

Exit Conditions: 

Depend upon function code 

Currently, all of the function codes defined by Microware for 
SCF-type devices are handled by IOMAN or SCFMAN. Any 
codes not defined by Microware are passed to the device driver. 

It may be necessary to examine or change the register stack that 
contains the values of the 6X(W registers at the time of the call. 
The address of the register stack may be found in PD.RGS, 
which is located in the path descriptor. 
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The following offsets may be used to access any value in the 
register packet: 



Term 



Name 


Relative 


Size 


680** Register 




Address 


(Bytes) 




R$CC 


$00 




Conditions Code Register 


RSI) 


$01 




Register I) 


R$A 


SOI 




Register A 


R$B 


$02 




Register B 


R$[)P 


$(tf 




Register DP 


R$X 


$04 


i 


Register X 


R$Y 


$06 


2 


Register Y 


R$U 


$08 


i 


Register U 


R$PC 


$0A 


2 


Program Counler 



Function: 

Terminate a device. This routine is called when a device is no 
longer in use (when the link count of its device descriptor 
module becomes zero). 

Entry Conditions: 

U = pointer to the device memory area 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 

Technical Function: 

1 . Wait until the output buffer is emptied (by the IRQ 
service routine). 

2. Disable the device interrupts. 

3. Remove the device from the IRQ polling list. 



64 



Note: Permanent storage used by device drivers is 
never returned to the free memory pool. Therefore, 
you should not terminate any device that might be 
used again. Modules contained in the Boot file will 
never be terminated. 



IRQ Service Routine 



This routine is not included in the device driver's branch table 
and is not called directly by SCFMAN, but it is a key routine in 
device drivers. 

The IRQ service routine services device interrupts, and when 
I/O is complete, it sends a wakeup signal to the process whose 
process ID is in V.WAKE. It also clears V.WAKE as a flag to 
the mainline program that the IRQ has occurred. 

When it finishes servicing an interrupt, the routine must clear 
the carry and exit with an RTS instruction. 

For technical information, see " IRQ Service Routine" in Chap- 
ter 5. 
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7 / Assembly-Language 
Programming Techniques 



There are four key rules to follow when you write OS -9 assem- 
bly-language programs: 

• The program must use position- independent eode 
(PIC). OS-9 seleets program load addresses based on 
available memory at runtime. You cannot select them. 

• The program must use the standard OS-9 memory 
module format; otherwise, it cannot be loaded and run. 
It cannot use self-modifying code. It must not change 
anything in a memory module or use any part of the 
module for variables. 

• Storage for all variables and data structures must be 
within the data area OS-9 assigns at runtime. This area 
is separate from the program memory module. 

• All input and output operations should be made using 
OS-9 system calls. 

The 6809's versatile addressing modes make it easy for you to 
follow these rules. The OS-9 assembler also helps; it has special 
capabilities to assist you in creating programs and memory 
modules for the OS-9 execution environment. 



How to Write Position-Independent Code 



The 6809 instruction set allows efficient use of position- 
independent code. 

The basic technique is to always use PC-relative addressing — 
for example, BRA, LBRA, BSR and LBSR. Get addresses of 
constants and tables using LHA instructions instead of load 
immediate instructions. If you use dispatch tables, use tables of 
relative addresses, not absolute addresses. 

Incorrect Correct 

LDX #CONSTANT LLAX CONSTANT. PCR 

JSR SUBR BSR SUBR or LBSR SUBR 

JMP LABEL BRA LABLL or LBRA LABLL 
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Addressing Variables and Data Structures 



A program that is executed as a process (by the Fork and Chain 
system calls or by the shell) is assigned part of RAM for 
variables, stacks, and data structures at execution time. The 
RAM area cannot be specified or determined ahead of time. 
However, a minimum si/e for the area is specified in the 
program's module header. 

When the program is first entered. Register Y contains the 
address of the top bound of the process's data memory area. 
Register U contains the address of the lower bound, and Regis- 
ter DP contains the area's page number. 

The creating process may have passed a parameter area. If so, 
this parameter area is located from the value of X and the SP to 
the top of memory (Register Y), and Register D contains the 
area's size in bytes. 

If the new process was called by the shell, the parameter area 
contains the part of the shell command line that includes the 
argument (parameter) text. (I/O redirection arguments are not 
included.) 

The most important rule is this: Do not use extended addres- 
sing. You should use only indexed and direct page addressing to 
access data area values and structures. Do not use program- 
counter relative addressing to find addresses in the data area, but 
do use it to refer to addresses within the program area. 

The most efficient way to handle tables, buffers, and stacks is to 
have the program's initialization routine compute their absolute 
addresses. It does this, using the data area bounds passed by 
OS-9 in the registers. 

The absolute addresses then can be saved in the direct page 
where they can be loaded into registers quickly, using short 
instructions. Direct page addressing has these advantages: it is 
faster than extended addressing, and the program is inherently 
reentrant. 
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Stack Requirements 



OS-9 uses interrupts extensively, and many reentrant 6809 
programs use the 6809 register staek for local variable storage. 
Because of this, a generous stack should be maintained at all 
times. We recommend no fewer than 200 bytes. 



Interrupt Masks 



User programs should keep the Hand I bits (FIRQ mask and IRQ 
mask) of the Condition Codes Register off. To avoid task- 
switching or interrupts during critical program sequences, you 
can set these bits. You should set them for no longer than a tick, 
however. Otherwise, system time-keeping may no longer be 
accurate. 



Using Standard I/O Paths 



Write your programs to use standard I/O paths wherever practi- 
cal. Usually, this involves I/O calls that are intended to com- 
municate to the user's terminal, or any other case where the 
OS-9 redirected I/O capability is desirable. 

All three standard I/O paths are open when the program is 
entered; they are inherited from the parent process. Programs 
should not close these paths except under special 
circumstances. 
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The standard I/O paths arc assigned as follows: 

• Path — Standard input . Analogous to the keyboard or 
other main data input source. 

• Path I — Standard output. Analogous to the terminal 
display or other main data output destination. 

• Path 2 — Standard error/status. This path is provided 
so output messages that arc not part of the actual 
program output can he kept separate. Paths 1 and 2 are 
often directed to the same device. 



Writing Interrupt-Driven Device Drivers 



OS-9 programs do not use interrupts directly. Any interrupt- 
driven function should be implemented as a device driver mod- 
ule which should handle all interrupt-related functions. When a 
program must be synchronized to an interrupt-causing event, a 
driver can send a semaphore to a program (or vice versa), using 
OS-9's signal facilities. 

It is important to understand that interrupt service routines arc 
asynchronous and are not distinct processes. They are, in effect, 
subroutines called by OS-9 when an interrupt occurs. 

Therefore, all interrupt-driven device drivers have two basic 
parts: the " 'mainline" ' subroutines that execute as part of the 
calling process, and a separate interrupt service routine, The 
two routines are asynchronous and therefore must use signals 
for communications and coordination. 

The Init initialization subroutine within the driver package 
should do the following: 

1 . Allocate memory area for the service routine 

2. Get the service routine address 

3. Execute the Set IRQ system call to add it to the IRQ 
polling table 
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When a device driver routine does something that results in an 
interrupt, it should immediately execute a Sleep system call. 
This turns off the process. 

When the interrupt occurs, its service routine is executed after 
some random interval. It should then do the least amount of 
processing required, and send a wakcup signal to its associated 
process using the Send system call. It may also put some data in 
its memory area (I/O data and status), which is shared with its 
associated sleeping process. 

Later, the signal awakens the device driver mainline routine. 
The routine can now process the data or status returned by the 
interrupt service routine. 
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The OS- 1 ) List utility command program is shown on this 
and the next page as an example of assembly-language 
programming. 



Microware OS-9 Assembler RS Version 01. 00.00 
LIST — OS-9 System Symbol Definitions 



06- 1 7 '83 13:06:11 Pane 001 



0000 1 




*■-*■*-*## - 


00002 




* 




00003 




* 


LIST 


0000a 




* 


S v n t 


00005 




* 


COP II 


0000B 




* 




00007 








0000B 




# 


NOTE 


00009 




* 




0001 








00012 








00013 




001 1 




00014 




0081 




00015 




0000 


87CD 


0001G 




* 


NOTE 


00017 




* 


LSTE 


0001B 




000D 


acag 


00019 




* 




00020 




* 


STAT 


00021 




* 




00022 




00CS 




00023 


D 


0000 




0002a 


D 


0000 




00025 


D 


0001 




0002B 


D 


0003 




00027 


D 


00CB 




00028 


D 


0193 




00029 


D 


025B 




00030 




001 1 


9F01 


00031 




0013 


8B01 


00032 




0015 


103F 


00033 




0018 


252E 


0003a 




001A 


3700 


00035 




001C 


9F01 


0003G 




001E 


9G00 


00037 




0020 


30a3 


00038 




0022 


108E 



UTILITY COMMAND 
ax: list ■ pathname ■ 
ES INPUT FROM SPECIFIED FILE TO STANDARD OUTPUT 

NAM LIST 
; A USE /D0/DEFS/OS9DEFS 

IS ENCLOSED WITHIN THE IFP1/ENDC STATEMENT 
IFP1 
ENDC 
TYPE SET PRGRM+OB 
REl J 5 SET REENT+1 
004E MOD LSTENDtLSTN 

REENT + 1 ,L 
CMD CONSISTS OF: 



5JCT 



AM ,PRGRM+OBJECT 
STENT t 



THE ^MOD' 
ND fLSTNAM t RPGRM+OB JECT ,REENT+1 
5304 LSTNAM FCS "LIST" 

IC STORAGE OFFSETS 



LSTENT ,LSTMEM 



BUFSIZ 

IPATH 

PRMPTR 

DUFFER 



e <3 u 
o r £f 
r hi b 
r m b 
r hi b 
r m b 
r m b 



LSTMEM EQU 

LSTENT stx 

1 da 

059 

bes 
s t a 

s t x 

1 da 



LIST20 



1 e ax 
1 d v 



200 


1 

bufsi; 

200 
200 



PRMPTR 

ttread 

I $ o p e n 
LIST50 
IPATH 

PRMPTR 

IPATH 

BUFFER ,U 
#BUFSIZ 



s i ; 



of irip u t buffer 



input path n u m her 
parameter pointer 
allocate 1 i n p buffer 
allocate s t a c K 
room for parameter 
list 



s a" 
sel 

m 
ope 
e x i 
s ai.i 

n 
5 au 

p 
1 o a 

n 
1 o a 
hi ax 



e c t 
ode 
n i 
t l 
e i 

U fri b 

e u 



t r 
d l 
u m b 
d b 
i m u 
ead 



ara meter ptr 
read access 

nput file 
f error 
nput path 
e r 
pdated pa ram 

n p a t path 

e r 

u f f e r Ptr 

hi bvtes to be 
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00039 002B 10 3F8B os9 1$ re ad In read line of input 

00040 0029 2503 Pes LIST30 exit if error 

00041 002B 8B01 Ida *1 load std. out path 

00042 002D 103F8C os3 I*writlrt output the line 

00043 0030 24EC bcc LIST20 repeat if no error 

00044 0032 2014 bra LIST50 exit if error 

00045 0034 C1D3 LIST30 cwpb »E$EOF at end of file? 
0004G 003G 2S10 bne LIST50 branch if not 

00047 0038 9B00 Ida IPATH load input path 

n u m b e r 

00048 003A 103F8F os8 Ifclose close input path 
00043 003D 2509 bcs LIST50 ».exit if error 

00050 003F 9E01 ldx PRMPTR restore para m p t r 

00051 0041 AGB4 Ida 0,X 

00052 0043 810D cinpa **$0D end of parameter 

line? 

00053 0045 2GCA bne LSTENT ««noi list next file 

00054 0047 5F clrb 

00055 0048 103F0B LIST50 os9 F$exit .♦♦terminate 
0005G 004B BF7G90 ewod module crc 

00057 004E LSTEND equ * 

00058 end 

00000 error(s) 
0000 warnings) 



Microware OS-9 Assembler RS Version 01 .00.00 06-17/83 13:1 1:28 Page 002 
LIST — OS-9 System Symbol Definitions 



$004E 00078 program bytes Generated 
$025B 00B03 data bytes allocated 
$ 1 C A E bvtes used for symbols 
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8 / System Calls 



System calls arc used to communicate between the OS-9 operat- 
ing system and assembly-language programs. There are two 
major types of calls — I/O calls and function calls. Function 
calls include user mode calls and system mode calls. 

Each system call has a mnemonic name. Names of I/O calls start 
with 1$. For example, the Change Directory call is I$chgdir. 
Names of function calls start with F$. For example, the Allocate 
Bits call is F$allbit. The names are defined in the assembler- 
entry conditions equate file called OS9Defs. 



The I/O calls are: 




Attach 


Make Directory 


Change Directory 


Open Path 


Close Path 


Read 


Create File 


Read Line 


Delete File 


Seek 


Detach Device 


Set Status 


Duplicate Path 


Write 


Get Status 


Write Line 


The user calls arc: 




Allocate Bits 


Parse Name 


Chain 


Print Error 


Compare Names 


Search Bits 


CRC 


Send 


Deallocate Bits 


Set Priority 


Exit 


Set SVC 


Fork 


Set SWI 


Get ID 


Set Time 


Intercept 


Sleep 


Link 


Time 


Load 


Unlink 


Memory 


Wait 
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The system mode calls are: 

Allocate 64 Request Sysmem 

Find 64 Return 64 

I/O Delete Return Sysmem 

I/O Queue Set IRQ 

Insert Process Verify Module 
Next Process 

System mode calls are privileged. They may be executed only 
while OS- 1 ) is in the system stale (when it is processing another 
system call, executing a file manager or device driver, and so 
on). 

System mode calls are included in this manual primarily for 
programmers who will be writing device drivers and other 
system- level applications. In the "System Call Descriptions 11 
section of this chapter, system mode calls are listed separately 
from I/O and user calls. 

Appendices A and B, the system call quick reference lists, 
summarize each system call's function. 



Calling Procedure 



All system calls are executed via an SVVI2 instruction . 

1. Load the 6809 register with any appropriate 
parameters. 

2. Execute a SWI2 instruction, followed immediately 
by a constant byte, which is the request code. 

3. After OS-9 processes the call, it returns any param- 
eters in the 6809 register. If an error occurred, the C 
bit of the Condition Code Register is set, and Accu- 
mulator B contains the appropriate error code. This 
permits a BCS or BCC instruction immediately 
following the system call to branch on error/no 
error. 
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As an example, here is the Close system call: 

LDA PATHNUM 

SWI2 

FCB $8B 

BCS KRROR 

You can use the assembler's "OS9" directive to simplify the 
call. Here is the simplified Close system call: 

LDA PATHNUM 
OS9 LSCLOSK 
BCS KRROR 

OS-9 accepts system calls in any combination of upper- or 
lower-case letters. 



I/O System Calls 



OS-9's I/O calls are easier to use than man) other systems' I/O 
calls. This is because the calling program does not have to 
allocate and set up "file control blocks", "sector buffers/' and 
so on. 

Instead, OS-9 returns a 1 -byte path number when a path to a 
file/device is opened or created. Until the path is closed, this 
path number may be used in later I/O requests to identify the file 
or device. 

In addition, OS-9 allocates and maintains its own data struc- 
tures. You need not deal with them. 



System Call Descriptions 



The rest of this chapter consists of the system call descriptions. 
At the top of each description is the system call name, followed 
by its mnemonic and code. Next is a summary oi the call's 
function, entry conditions, and exit conditions. When further 
explanation is required, it is included under a section called 
"Technical Function." 
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In the system call descriptions, registers not specified as entry or 
exit conditions arc not altered. Strings passed as parameters are 
normally terminated by having Bit 7 of the last character set, a 
space character, or an end -of- line character. 

If an error occurs on a system call, the C bit of Register CC is 
set, and Register B contains the error code. If no error occurs, 
the C bit is clear, and Register B contains a value of zero. 
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Allocate Bits 



OS9 F$allbit 



103F 13 



Function: 

Sets bits in the allocation bit map specified by Register X. 

Bit numbers range from to n-I , where n is the number of bits in 
the allocation bit map. 

Entry Conditions: 

X = starting address of the allocation hit map 

D = numher of the first hit to set 

Y — numher of hits to set 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 
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Attach 

OS9 I$attach 



103F 80 



Function: 

Attaches a new device to the system or verifies that a device is 
attached. 

Attach docs not ' 'reserve' ' the device. It only prepares it for 
later use by any process. 

Most devices are installed automatically. Therefore, you need 
to use Attach only when installing a device dynamically or when 
verifying the existence of a device. You need not use the Attach 
system call to perform routine I/O. 

The access mode parameter specifies the read and/or write 
operations to he allowed. These are: 

= Use device capabilities 

1 = Read 

2 = Write 

3 = Update 

Entry Conditions: 

X — address of the device name string 

A = access mode 

Exit Conditions: 

U = address of the device table entry 

If error: 

CC = C bit set 

B = error code 
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Technical Function: 

I . OS-9 searches the system module to sec if memory 
contains a device descriptor that has the same name 
as the device. 

2a. If it finds the descriptor and if the device is not 
already attached, OS-9 links to its file manager and 
device driver. It then places their addresses in a new 
device table entry. OS-9 then allocates any memory 
needed by the device driver and calls the driver's 
initialization routine (which usually initializes the 
hardware). 

2b. If it finds the descriptor and if the device is already 
attached, OS-9 does not reinitialize the device. 
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Chain 

OS9 F$chain 



103F 05 



Function: 

Loads and executes a new primary module, but does not create a 
new process. A Chain system call is similar to a Fork followed 
by an Exit, but with less processing overhead. 

Chain "resets" the calling process's program and data memory 
areas and begins executing a new primary module. It does not 
affect open paths. 

Warning: The hardware stack pointer (Register SP) should be 
located somewhere in the direct page before the Chain is ex- 
ecuted. This helps prevent a "suicide"' (system crash) or a 
"suicide attempt" error. It also prevents a suicide in the event 
that the new module requires a smaller data area than that in use. 
You should allow approximately 200 bytes of stack space for 
execution of the Chain system call. 

Entry Conditions: 

X = address of the module name or filename 

Y — parameter area size (in pages); defaults to 

zero if not specified 
Li = starting address of the parameter area 

A = language I type code 

B ~ size of the data area (in pages); must be at 

least one page 

Exit Conditions: 

None 



If error: 




CC 


= C bit set 


B 


= error code 



Technical Function: 



OS-9 passes the name string of the new process's 
primary module (the program that is to be executed 
first). Then, it searches the system module direc- 
tory to see if a module with the same name, type, 
and language is already in memory. 
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2a. If the module is in memory, it is linked to. 

2b. If the module is not in memory, the name string is 
used as the pathlist of a file which is to be loaded 
into memory. Then, the first module in this file is 
"linked to." (Several modules may have been 
loaded from a single file.) 

3. OS-9 unlinks the process's old primary module. 

4. The data memory area is reconfigured to the size 
specified in the new primary module's header. 

The diagram below shows how Chain sets up the data memory 
area and registers for the new module. 



Direct Pa tie 



Data Area 



Parameter 
Area 



l", DP (lowest address) 



X. SP 



Y (highest address) 



D = parameter area size 

PC = module entry point absolute address 

CC = F = (), 1=0; others are undefined 

Registers Y and U (the top-of-memory and bottom-of-memory 
pointers, respectively) always have values at page boundaries. 
If the parent process does not specify a size for the parameter 
area, the size (Register D) defaults to zero. The data area must 
be at least one page long. 

(For more information, see the Fork system call.) 
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Change Directory 



OS9 I$chgdir 103F 86 

Function: 

Changes a process's working directory to the directory specified 
by the pathlist. 

If the access mode is read, write, or update, the current data 
directory is changed. If the access mode is execute, the current 
execution directory is changed. 

The calling process must have read access to the directory 
specified (public read if the directory is not owned by the calling 
process). 

The access modes are: 

1 = Read 

2 = Write 

3 = Update 

4 = Hxecute 

Entry Conditions: 

X = address of the pathlist 

A = access mode 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 
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Close Path 



OS9 ISclose 103F 8F 



Function: 

Terminates the I/O path to the file or device specified by the 
path number. Unless you use another Open or Create system 
call, you can no longer perform I/O to the file or device. 

Non-sharable devices become available to other requesting pro- 
cesses. All OS-9 internally managed buffers and descriptors are 
deallocated. 

The Exit system call automatically closes all open paths (except 
the standard I/O paths). Therefore, you may not need to use the 
Close Path system call to close them. 

Do not close standard I/O paths unless you want to change the 
files or devices to which they correspond. 

Entry Conditions: 

A = path number 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 
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Compare Names 



OS9 F$cmpnam 103F 11 

Function: 

Compares two strings and indicates whether they match. Use 
this call with the Parse Names system call. 

The second name must have the most significant bit (Bit 7) of 
the last character set. 



Entry Conditions: 

X = address of string I 

B = length of string! 

Y — address of string! 

Exit Conditions: 

CC = C bit clear if the strings match 

It' error: 

CC - C bit set 

B — error code 
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CRC 

0S9 F$crc 103F 17 



Function: 

Calculates the CRC (cyclic redundancy count) for use by com- 
pilers, assemblers, or other module generators. 

The calculation begins at the starting byte address and continues 
over the specified number of bytes. 

You need not cover an entire module in one call, since the CRC 
may be "accumulated" over several calls. The CRC accumula- 
tor can be any 3-byte memory area and must be initialized to 
$FFFFFF before the first CRC call. 

The last three bytes in the module are not included in the CRC 
generation. The three CRC bytes are to be stored here. 

Entry Conditions: 

X — starting byte address 

Y = number of bytes 

D — address of the 3 -byte CRC accumulator 

Exit Conditions: 

The CRC accumulator is updated. 

If error: 
None 



87 



Create File 



OS9 I$create 



103F 83 



Function: 

Creates and opens a file on a disk. 

OS-9 parses the pathlist and enters the new filename in the 
specified directory — or the working directory, if none is 
specified. 

The file is given the attributes passed in Register B, which has 
bits defined as follows: 



Bit 


Definition 





Read 


1 


Write 


2 


Execute 


3 


Public read 


4 


Public write 


5 


Public execute 


6 


Sharable file 



The access mode parameter passed in Register A must be either 
write or update. This mode affects the file only until it is closed. 
The file can be reopened in any access mode allowed by the file 
attributes (see the Open system call). 

Files opened for write may allow faster data transfer than those 
opened for update because update sometimes needs to pre-read 
sectors. These access codes are defined as follows: Bit 2 — 
write; Bit 3 = update. 

Note: If the execute bit (Bit 2) is set, the file is created in 
the working execution directory instead of the working 
data directory. 

The path number returned by OS-9 is used to identify the file in 
later I/O system calls until the file is closed. 

No data storage is initially allocated for the file at the time it is 
created. This is done automatically by the Write subroutine or 
explicitly by the Setsta subroutine. 
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If the filename already exists in the directory, an error occurs. If 
the call specifies a non-multiple file device (such as a printer or 
terminal). Create behaves the same as an Open. 

You cannot use Create to make directories. (See the Make 
Directory system call for instructions on how to do this.) 

Entry Conditions: 



X 
A 
B 

Kxit Conditions: 



address of the pathlisi (see example below) 
access mode 
file attributes 



-- address of the last byte of the pathlist I /; 

any trailing blanks are skipped (see example 

below) 
=■ path number 





If error 












CC 


— 


C bit 


set 






B 


- 


error 


code 




K 


xample: 












Before 


the 


Create 


File c< 


ill 



1 / 


I) 





'' 


w 





R 


K 


$01) 



t 

X 



After the Create File call 



' 


D 







W 





R 


K 


sod 
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Deallocate Bits 



OS9 F$delbit 103F 14 

Function: 

Clears bits in the allocation bit map pointed to by Register X. 

Bit numbers range from () to /;-/ . where n is the number of bits 
in the allocation bit map. 

Entry Conditions: 

X = star tins!, address of the all oval ion hit map 

D = number of the first hit to set 

Y = number of bits to set 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error eode 
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Delete File 



0S9 I$delete 



103F 87 



Function: 

Deletes the disk file specified by the pathlist. 

The file must have write permission attributes (public write if 
the calling process is not the owner). 

An attempt to delete a device results in an error. 

Entry Conditions: 

X — address of the pathlist (see example below) 

Exit Conditions: 

X = address of the last byte of the pathlist f- /; 

any trailing blanks are skipped (see example 
below) 

If error: 

CC - C bit set 

B = error code 

Example: 

Before the Delete File call; 



/ 


D 





/ 


W 





R 


K 


b 


b 


b 


M 


F 


M 


() 


SOI) 



t 

X 



After the Delete File call; 



/ 


I) 







w 





R 


K 


b 


b 


b 


M 


H 


M 


() 


SOD 



t 

X 
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Detach Device 



OS9 I$detach 



103F 81 



Function: 

Removes a device from the system and the system device table, 
if the device is not being used by another other process. 

You must use this call to detach devices that were attached using 
the Attach system call. Both calls are used mainly by IONIAN. 
SCFMAN also uses Attach/Detach to set up its second device 
(echo device). 

Entry Conditions: 

U = address of the device table entry 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B — error code 

Technical Function: 

1. The device driver's termination routine is called, 
then OS-9 deallocates any memory assigned to the 
driver. 

2. The associated device driver and file manager mod- 
ules are unlinked. If not being used by any other 
module, the driver is removed from RAM. 
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Duplicate Path 



0S9 I$dup 103F 82 

Function: 

Returns another, synonymous path number for the file or device 
specified by the old path number. 

The shell uses this system call when it redirects I/O. System 
calls that use either path number (old or new) operate on the 
same file or device. 



Entry Conditions: 



old path number (number of path to 
duplicate) 



Exit Conditions: 

B = new path number 

If error: 

CC = C bit set 

B = error code 
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Exit 

OS9 F$exit 103F 06 

Function: 

Terminates the calling process. 

The Hxit system call is the only way a process can "kill" itself. 
Exit deallocates the process's data memory area and unlinks its 
primary module. It also closes all open paths automatically. 

The Wait system call always returns to the parent the status code 
passed by the child in its Hxit call. Therefore, if the parent 
executes a Wait and receives the status code, it knows the child 
has "died/* 

Entry Conditions: 

B — status code to return to the parent 

Exit Conditions: 

The process is terminated. 



Fork 

OS9 F$fork 



103F 03 



Function: 

Creates a new process, a "child*" of the calling process. Fork 
also sets up the child process's memory and 6809 register. 



Entry Conditions: 

X 



u 

A 
B 



— address of the module name or filename (see 
example below) 

= size of the parameter area i in pages ); defaults 
to zero if not specified 

— starting address of the parameter area 
= language/lype code 

= size of the optional data area (in pages); must 
be at least one page 



Exit Conditions: 

X 



address of the last byte of the name + / (see 
example below) 



It error: 

CC = C bit set 

B — error eode 



Example: 



Before the Fork eal 



T 


F 


S 


T 


$01) 



t 

X 

After the Fork call: 



T 


F 


S 


T 


$()0 



t 

X 
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Technical Function: 

1 . OS-9 passes the name string of the new process's 
"primary module" (the program that is to be ex- 
ecuted first). Then, it searches the system mod- 
ule directory to see if the program already is in 
memory. 

2a. If the program is in memory, the module is linked to 
and executed. 

2b. If the program is not in memory, OS-9 uses the 
name as the pathlist of the file that is to be loaded 
into memory. Then, the first module in this file is 
linked to and executed. (Several modules may have 
been loaded from one file.) 

3. OS- - uses the primary module's header to deter- 
mine the initial si/e of the process's data area. It 
then tries to allocate a contiguous RAM area of that 
si/e. (This area includes the parameter passing 
area, which is copied from the parent process's data 
area. ) 

4. The new process's registers are set up as shown in 
the diagram on the next page. The execution offset 
given in the module header is used to set the PC] to 
the module's entry point. 

When the shell processes a command line, it passes a string in 
the parameter area. This string is a copy of the parameter part of 
the command line. To simplify string-oriented processing, it 
also inserts an end-of-line character at the end of the parameter 
string. 

Register X points to the starting of the parameter string. If the 
command line included the optional memory size specification 
(#/? or #/jK), the shell passes that as the requested memory size 
when executing the Fork. 

If any of the above operations is unsuccessful, the Fork is 
aborted and the caller is returned an error. 

The diagram below shows how Fork sets up the data memory 
area and registers for a newly created process. 
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Direct Pane 



Data Area 



Parameter- 
Area 



l'. DP (lowest address) 



X, SP 



I h i u he st address) 



D = size of the parameter area 

PC = module entry point ahsoiuie address 

CC — F = 0, 1=0, others arc undefined 

Registers Y and U {the top-of-memory pointer and bottom-of- 
memory pointer, respectively) always have values at page 
boundaries. 

As stated earlier under "Kntry Conditions," if the parent does 
not specify the si/e of the parameter area, the size defaults to 
zero. The minimum overall data area si/e is one page. 

Note: The child and parent processes execute at the same 
time. If the parent executes a Wait system call immediate- 
ly after the Fork, it waits until the child "dies" before it 
resumes execution. 

Be careful when recursively calling a program that uses 
the Fork system call; another child may be created with 
each "incarnation." This continues until the process table 
becomes full. 
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Get ID 

OS9 F$id 103F oc 

Function: 

Returns the caller's process ID and user ID. 

The process ID is a byte value from 1 to 255. It is assigned by 
OS-9 and is unique to the process. 

The user ID is an integer from to 65535. It is defined in the 
system password file, and is used by the file security system and 
a few other functions. Several processes can have the same user 
IL). 



Entry Conditions: 


None 




Exit Conditions: 




A 


process ID 


Y 


user ID 


If error: 




CC 


C bit set 


B 


error code 
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Get Status 



OS9 I$gttstt 



103F 8D 



Function: 

Returns the status of a file or device. 

This is a "wildcard" call. It is used to handle device parameters 
that: 



• Are not the same for all devices 

• Are highly hardware-dependent 

• Must be user changeable 

The exact operation of the Get Status system call depends on the 
device driver and file manager associated with the path. A 
typical use is to determine a terminal \s parameters for such 
functions as backspace character and echo on/off. The Get 
Status call is commonly used with the Set Status call. 

The Get Status function codes that are currently defined are 
listed in the "Uses of Get Status" section below. 

Entry Conditions: 

A = path number 

X = MS 16 hits of the desired file position 

U — LS 16 hits of the desired file position 

Exit Conditions: 



N 



one 



Uses of Get Status 



If error: 

CC = C bit set 

B = error code 



Function codes 7 through 127 are reserved for future use. 

Codes 128 through 255 and their parameter-passing conven- 
tions are user-definable. (See the sections on writing device 
drivers). The function code and register stack are passed to the 
device driver. 
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The following function codes are defined: $00, $01 , $02, $05, 
$06, $12, and $ 13. The parameter-passing conventions for 
these function codes are listed below. 

SS.OPT (Function code $00): Reads the option section of the 
path descriptor, and copies it into the 32-byte area pointed to by 
Register X. 

Use this to determine the current settings for editing functions, 
such as echo and auto line feed. For a complete description of 
the status packet, see the section on path descriptors. 

Entry Conditions: 

A = path number 

B - $00 

X = address to receive status packet 

Exit Conditions: 
Status packet 

If error: 

CC = C bit set 

B = error code 

SS.RDY (Function code $01): Tests for data available on 
SCFMAN-supported devices. 

Entry Conditions: 

A = path number 

B - $01 



Exit Conditions: 
If ready: 

CC - C bit clear 

B - $00 

If not ready: 

CC - C bit set 

B = $F6 (E$SRNDY) 

If error: 

CC = C bit set 

B — error code 
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SS.SIZ (Function code $02): Gets the current file size 
(RBFM AN- supported devices only). 

Entry Conditions 

A = path number 

B - $02 

Exit Conditions 

X = ms 16 bits of the current file size 

U = Is 16 bits of the current file size 

If error: 

CC - C bit set 

B = error code 

SS.POS (Function code $05): Gets the current file position 
(RBFM AN -supported devices only). 

Entry Conditions: 

A = path number 

B = $05 

Exit Conditions: 

X = MS 16 bits of the current file position 

U = LS 16 bits of the current file position 

If error: 

CC = C bit set 

B = error code 

SS.EOF (Function code $06): Tests for the end of the file 
(EOF). 

Entry Conditions: 

A = path number 

B = $06 

Exit Conditions: 
If not EOF: 

CC - C bit clear 

B - $00 

If EOF: 

CC - C bit set 

B - $D3 (ESEOF) 
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If error: 




CC 


= C bit set 


B 


- error code 



SS.DSTAT (Function code $12): Returns the display status. 

Entry Conditions: 

A = path number 

B - $12 

Exit Conditions: 

X = address of the graphics display memory 

Y = graphics cursor address; x = MSB, 

y = LSB 
A — color code of the pixel at the cursor address 

SS.JOY (Function code $13): Returns the joystick values. 

Entry Conditions: 

A = path number 

B = $13 

X =0 (right joystick), or 

X = 1 (left joystick) 

Exit Conditions: 

X = selected joystick .x value (0-63) 

Y — selected joystick v value (0-63) 
A = $FF (if the fire button is on), or 
A - $00 (if the fire button is oi'I") 
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Intercept 

OS9 F$icpt 103F 09 

Function: 

Tells OS-9 to set a signal intercept trap. Then, whenever the 
process receives a signal, the process's intercept routine is 
executed. 

Once the signal trap is set, the intercept routine may be executed 
at any time because a signal may occur at any time. 

The intercept routine should terminate with an RTI instruction. 

Note: If a process has not used the Intercept system call to set a 
signal trap, the process aborts if it receives a signal. 

Entry Conditions: 

a 

starting address of the routine's memory 



X 


address of 


u 


starting a 




area 


Exit Conditions: 




None 




If error: 




CC 


C bit set 


B 


error code 



Technical Function: 

1 . When the process receives a signal, OS-9 sets Reg- 
isters U and B as follows: 

U = starting address of the intercept 

routine's memory area 

B = signal code (process's termination 

status) 

Note: The value of Register DP may not be the 
same as it was when the Intercept call was made. 

2. After setting the registers, OS-9 transfers execution 
to the intercept routine. 
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Link 

OS9 F$link 



103F 00 



Function: 

Links to a memory module that has the specified name, lan- 
guage, and type. 

The module's "link count 11 is incremented whenever Link 
references its name. This keeps track of how many processes are 
using the module. 

If the module requested is not sharable {not reentrant), only one 
process may link to it at a time. 

Entry Conditions: 

X = address of the module name (see example 

below) 
A = type/language byte 



Exit Conditions: 

X 

Y 
U 
A 
B 



address of the last byte of the module name 

+ / (see example below) 

module entry point absolute address 

module header absolute address 

type I language code 

attributes i revision level 



If error: 

CC 

13 



C bit set 
error code 



Example: 

Before the Link cal 



T 


E 


S 


T 


$0D 
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After the Link call: 



T 


E 


S 


T 


SOD 



I 

X 



Technical Function: 



2b. 



OS-9 searches the module directory for a module 
that has the specified name, language, and type. 

If OS-9 finds the module, the address of the mod- 
ule's header is returned in Register U, and the 
absolute address o( the module's execution entry 
point is returned in Register Y. (This and other 
information can be obtained from the module 
header.) 

If OS-9 doesn't find the module — - or if the type/ 
language codes in the entry and exit conditions 
don't match — OS-9 returns an error. 



Possible Errors: 

• Module not found 

• Module busy (not sharable and in use) 

• Incorrect or defective module header 
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Load 

OS9 F$load 



103F 01 



Function: 

Loads a module or modules from the file specified by the 
pathlist or from the working execution directory (if no pathlist is 
given). 

The file must have the execute access mode. It also must contain 
a module or modules that have a proper module header. 

All modules loaded are added to the system module directory. 
The first module read is linked. The exit conditions apply only 
to the first module loaded. 



Entry Conditions 
X 

A 
Exit Conditions 



= address of the pathlist (filename) (see exam- 
ple below) 
= language! type code: = any language/type 



X = address of the last byte of the pathlist (file- 

name) 4- / (sec example below) 
Y = primary module entry point address 

U = address of the module header 

A — language/type code 

B =- attributes I revision level 

If error: 

CC = C bit set 

B = error code 

Example: 

Before the Load call: 



/ 


D 





/ 


A 


C 


C 


T 


S 


R 


C 


V 


SOD 
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After the Load call: 



/ 


D 





/ 


A 


C 


C 


r 


s 


R 


C 


V 


SOD 



Possible errors: 



• Module directory full 

• Memory full 

• Errors that occur on the Open, Read, Close, and Link 
system calls 
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Make Directory 



OS9 I$makdir 103F 85 

Function: 

Creates and initializes a directory as specified by the pathlist. 
The directory contains no entries, except tor an entry for itself 
(.) and its parent directory (..) 

The caller is made the owner of the directory. Because the Make 
Directory call does not open the directory, it does not return a 
path number. 

The new directory automatically has its "directory"' bit set in 
the access permission attributes. The remaining attributes are 
specified by the byte passed in Register B. The bits are defined 
as follows: 



Bit 


Definition 





Read 


1 


Write 


2 


Execute 


3 


Public read 


4 


Public write 


5 


Public execute 


6 


Sh arable 


7 


Don't care 



Entry Conditions: 

X = address of the pathlist (see example below) 

B = directory attributes 

Exit Conditions: 

X = address of the last byte of the pathlist + /; 

any trailing blanks are skipped (see example 
below) 

If error: 

CC = C bit set 

B = error code 
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Example: 

Before the Make Directory call; 



/ 


D 





/ 


N 


H 


W 


D 


I 


R 


$01) 



After the Make Directory call; 



/ 


D 





/ 


N 


E 


W 


D 


I 


R 


$0D 
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Memory 
OS9 F$mem 



103F 07 



Function: 

Expands or contracts the process's data memory area to the 
specified size. Or, if you specify zero as the new size, the call 
returns the current size of data memory. 

The size requested is rounded off to the next page boundary. 
Additional memory is allocated contiguously upward or deallo- 
cated downward from the old highest address. 

Even if enough free memory exists, the call may return an error 
upon an expansion request. This is because the data area is 
always made contiguous. Therefore, memory requests by other 
processes may fragment free memory into smaller, scattered 
blocks that are contiguous with the caller's present data area. 

Entry Conditions: 

D ~ size of the new memory area (in bytes); 

— return current size and upper bound 



Exit Conditions: 



Y 
D 

If error: 

CC 

B 



address of the new memory area upper hound 
actual size of the new memory (in bytes) 



C bit set 
error code 
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Open Path 

OS9 I$open 103F 84 



Function: 

Opens a path to an existing file or device as specified by the 
pathlist. 

OS-9 searches for the file in one of the following: 

• The directory specified by the pathlist if the pathlist 
begins with a slash 

• The working data directory, if the pathlist does not 
begin with a slash 

• The working execution directory, if the pathlist does 
not begin with a slash and if the execution bit is set in 
the access mode 

A path number is returned; it is used in later system calls to 
identify the file. 

The access mode parameter specifies which read and/or write 
operations are to be permitted. When set, the bits allow access 
as follows: 

Bit(s) Access 

Read Read 

Write Write 

Read and write Update 

Directory Directory I/O 

The access mode must conform to the access permission attri- 
butes associated with the file or device (see the Create system 
call). Only the owner may access a file unless the appropriate 
"'public permit" bits are set. 

The update mode may be slightly slower than the others because 
pre-reading of sectors may be required for random access of 
bytes within sectors. 

Several processes (users) may open files at the same time. Each 
device has an attribute that specifies whether or not it is 
sh arable. 
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Entry Conditions: 

X = address of the pathlist (see example below) 

A - access mode (I) S PE PW PR HWR) 

Exit Conditions: 

X = address of the last byte of the pathlist 4- / 

(see example below) 
A = path number 

If error: 

CC = C bit set 

B = error code 

Example: 

Before the Open Path call: 



/ 


I) 





/ 


A 


C 


C 


T 


S 


P 


A 


Y 


SOD 



After the Open Path eal 



/ 


D 





/ 


A 


C 


C 


T 


S 


P 


A 


Y 


son 
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Parse Name 



OS9 F$prsnam 103F 10 



Function: 

Parses (analyzes) the input text string for a legal OS-9 name. 
The name is terminated by any character that is not a legal name 
character. 

This system call is useful for processing pathlist arguments 
passed to new processes. 

Because Parse Name processes only one name, several calls 
may be needed to process a pathlist that has more than one 
name. As you can see from the example below. Parse Name 
finishes with Register X in position for the next parse. 

If Register X was at the end of a pathlist, a bad name error is 
returned. Then, Register X is moved past any space characters 
so that the next pathlist in a command line may be parsed. 

Entry Conditions: 

X = address of the pathlist (see example below) 

Exit Conditions: 

X ~ address of the optional slash + / 

Y = address of the last character of the name 

-f / (see example below) 
B = length of the name 

If error: 

CC = C bit set 

B = error code 

X = address of the last trailing blank -\ I 
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Example: 

Before the Parse Name cal 





D 





/ 


P 


A 


Y 


R 


() 


I. 


I. 


b 


b 


b 



After the Parse Name call 



/ 


D 







P 


A 


Y 


R 


C) 


L 


L 


b 


b 


b 



t t 

X Y 
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Print Error 



OS9 F$perr 103F or 



Function: 

Writes an error message to the output path specified. By default, 
OS-9 displays: 

ERROR # decimal number 

The error reporting routine is vectored and can be replaced with 
a more elaborate reporting module. To replace this routine use 
the Set SVC system call. 



Entry Conditions: 






A 


output path 


number 


B 


error 


code 




Exit Conditions: 








None 








If error: 








CC 


Cbit 


set 




B 


error 


code 
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Read 

OS9 I$read 103F 89 



Function: 

Reads the specified number of bytes from the specified path. 
The data is returned exactly as read from the file/device without 
additional processing or editing. 

The path must have been opened in the read or update mode. 

After all data in a file is read, the next Read call returns an 
end-of-file error. 

The keyboard abort, keyboard interrupt, and end-of-file charac- 
ters may be filtered out of the entry conditions data on 
SCFMAN-type devices unless the corresponding entries in the 
path descriptor have been set to zero. You may want to modify 
the device descriptor so that these values are initialized to zero 
when the path is opened. 

The number of bytes requested is read unless any of the follow- 
ing is true: 

• An end-of-file occurs 

• An end-of- record occurs (SCFMAN only) 

• An error occurs 

Entry Conditions: 

X = address to store data 

Y = number of bytes to read 
A = path number 

Exit Conditions: 

Y = number of bytes read 

If error: 

CC = C bit set 

B = error code 
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Read Line 



OS9 I$readln 



103F 8B 



Function: 

Reads a text line with editing. 

Read Line is similar to Read except it reads the input file or 
device until a carriage return character is encountered or until 
the maximum byte count specified is reached. Line editing is 
also activated on character-oriented devices, such as terminals 
and printers. The line editing refers to auto line feed, null 
padding at the end of the line, backspacing, line deleting, and so 
on. 

SCFMAN requires that the last byte entered be an end -of- record 
character (usually a carriage return). If more data is entered than 
the maximum specified, it is not accepted and a PD.OVF 
character (usually bell) is echoed. 

After all data in a file is read, the next Read Line call generates 
an end-of-file error. 

(For more information about line editing, see "SCFMAN Line 
Editing Functions' 1 in Chapter 6.) 

Entry Conditions: 

X = starting address to store data 

Y = maximum number of bytes to read 
A = path number 

Exit Conditions: 

Y = number of bytes read 

If error: 

CC - C bit set 

B ~ error eode 
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Search Bits 



OS9 FSschbit 103F 12 



Function: 

Searches the specified allocation bit map for a free block 
(cleared bits) of the required length. 

The search starts at the starting bit number. If no block of the 
specified size exists, the call returns with the carry set, starting 
bit number, and size of the largest block. 

Entry Conditions: 



X 


= 


starting address of the map 


D 


= 


starting bit number 


Y 


= 


bit count (free bit block size) 


U 


= 


ending address of the map 


Exit Conditions: 




D 


= 


starting bit number 


Y 


= 


bit count 
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Seek 

OS9 I$seek 103F 88 



Function: 

Repositions the path's logical v Mlle pointer/' the 32-bit address 
of the next byte in the file to be read from or written to. 

A seek may be performed to any value, regardless of the file's 
size. Later writes automatically expand the file to the required 
size (if possible). Reads, however, return an end-of-file condi- 
tion. Note that a seek to Address is the same as a rewind 
operation. 

Seeks to non-random access devices usually are ignored and 
return without error. 

Entry Conditions: 

A = path number 

X = MS 16 hits of the desired file position 

U = LS 16 hits of the desired file position 

Exit Conditions: 

None 

If error: 

CC - C bit set 

B = error eode 
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Send 

OS9 F$send 103F 08 

Function: 

Sends a signal to the specified process. The signal code is a 
single byte value from 1 through 255. 

If the destination process is sleeping or waiting, it is activated so 
that it may process the signal. 

If a signal trap was set up, the signal processing routine (Inter- 
cept) is executed (see the Intercept system call). If none was set 
up, the signal aborts the destination process, and the signal code 
becomes the exit status (see the Wait system call). An exception 
is the wakeup signal; it does not cause the signal intercept 
routine to be executed. 

Signal codes are defined as follows: 

= System abort (cannot be intercepted) 

1 = Wake up the process 

2 = Keyboard abort 

3 = Keyboard interrupt 
4-255 = User defined 

If you try to send a signal to a process that has a signal pending, 
the current Send call is cancelled, and an error is returned. Issue 
a Sleep call for a few ticks, then try again. (The Sleep call saves 
CPU time.) 

(See the Intercept, Wait, and Sleep system calls for more 
information.) 

Entry Conditions: 



A 


destination 


B 


signal each 


Exit Conditions: 




None 




If error: 




CC 


C bit set 


B 


error code 
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Set Priority 

OS9 F$sprior 103F od 

Function: 

Changes the process's priority to the priority specified. 

A process can change another process's priority only if it has the 
same user ID. 

Entry Conditions: 

A — process ID 

B — priori rv: = lowest, 255 — highest 

Exit Conditions: 

None 

If error: 

CC - C hit set 

B — error code 
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Set Status 



OS9 I$setstt 



103F 8E 



Uses of Set Status 



Function: 

Sets the status oi a file or device. 

This is a "wildcard" call. It is used to handle device parameters 
that: 

• Are not the same for all devices 

• Are highly hardware-dependent 

• Must be user-changeable 

The exact operation of the Set Status system call depends on the 
device driver and tile manager associated with the path. A 
typical use is to set a terminal's parameters for such functions as 
backspace character and echo on/off. The Set Status call is 
commonly used with the Get Status call. 

The Set Status function codes that are currently defined are 
listed in the kt Uses of Set Status" section below. 

Entry Conditions: 

A — path number 

B = function code 

Other registers depend upon the function code 

Exit Conditions: 

Depend upon the function code 

If error: 

CC - C bit set 

B = error code 



Function codes 128 through 255 and their parameter-passing 
conventions are user-definable. (For more information, see the 
"RBF-Type Device Drivers" section in Chapter 5 and the 
"SCF-Type Device Drivers" section in Chapter 6.) The func- 
tion code and register stack are passed to the device driver. 
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The following function codes are defined: $00, $02, $04, $09, 
$0A, SOB, $0C, and $0D. The parameter-passing conventions 
for these function codes are listed below. 

SS.OPT (Function code $00): Writes the option section of the 

path descriptor from the 32-byte status packet pointed to by 
Register X. Use this to set the device operating parameters, such 
as echo and line feed. 

Entry Conditions: 

A = path number 

B - $00 

C = address of the status paeket 

Exit Conditions: 
None 

SS.SIZ (Function code $02): Changes the file's size 
(RBFMAN-type devices only). 

Entry Conditions: 

A = path number 

B = $02 

X = MS 16 bits of the desired file size 

U = LS 16 bits of the desired file size 

Exit Conditions: 
None 

SS.RST (Function code $03): Restores the head to Track 0. 
This is used for formatting and error recovery. 

Entry Conditions: 

A = path number 

B - $03 

Exit Conditions: 
None 



123 



SS.WTK (Function code $04): Formats (writes) a track on a 
floppy disk. For hard disks or floppy disks that have a "format 
entire disk command/' SS.WTK formats the entire disk only 
when the track number is zero. 

Entry Conditions: 

A = path number 

B - $04 

X - address of the track buffer 

U = track number (least significant 8 bits) 

Y = side i 'density 

Bit BO = side (0 - Side 0, 1 = Side 1) Bit 
Bl = density (0 = single, 1 = double) 

Exit Conditions: 
None 

SS.FEE (Function code $09): Issues a form feed. 

Entry Conditions: 

B = $09 

Exit Conditions: 
None 

SS.FRZ (Function code $0A): Freezes the DD. information. 
(Inhibits the reading of LSN to DDD.xxx variables, which 
define disk formats.) This enables the reading of non-standard 
disks. 

Entry Conditions: 

B - $0A 

Exit Conditions: 
None 

SS.SPT (Function code $0B): Sets a different number of sec- 
tors per track so non-standard disks may be read. 

Entry Conditions: 

B = $0B 

X = new sectors per track 

Exit Conditions: 
None 
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SS.SQI) (Function code $0C): Starts the power-down se- 
quenee for hard disks that have sequence-down requirements 
prior to removal of power. 

Entry Conditions: 

B - $()C 

Exit Conditions: 
None 

SS.DCM (Function code $01)): Transmits a command directly 
to a disk controller for specific functions. Parameters and com- 
mands arc hardware-dependent for specific systems. 

Entry Conditions; 

B - SOD 

Other registers vary 

Exit Conditions: 
Vary 
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Set SVC 

OS9 F$ssvc 



103F 32 



Function: 

Adds or replaces a system call, which you have written, in 
OS-9's user and system mode system call tables. 

Entry Conditions: 

Y = address of the system call initialization table 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 

Technical Function: 

1. Register Y passes the address of a table, which 
contains the function codes and offsets, to the cor- 
responding system call handler routines. This table 
has the following format: 



Relative 
Address 

$00 
$01 

$02 
$03 
$04 

$05 



Use 



Function Code 



Offset From Byte 3 
To ['unction Handler 



Function Code 



Offset From Byte 6 
To Function Handler- 



More Entries 



$80 



-« First entry 



-« Second entry 



- Third entry 



- End-of-table mark 
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2a. If the most significant bit of the function code is set, 
the system table is updated. 

2b. If the most significant bit of the function code is not 
set, the system and user tables arc updated. 

Function request codes are broken into these two categories: 

$00 - $27 User mode system call codes. 

$29 - $34 Privileged system mode system call 

codes. When these system calls are 
being installed, the most significant 
bit should be set if it is to be placed 
into the system table only. 

These categories are defined by convention; they are not en- 
forced by OS-9. 

To use a privileged system call, you must be executing a 
program that has the type code $()C (OS-9 system module). 

The system call handler routine should process the system call 
and return from subroutine with an RTS instruction. The hand- 
ler routine may alter all CPU registers (except Register SP). 
Register U passes the address of the register stack to the system 
call handler as shown in the following diagram: 



CC 




A 




B 




DP 




X 


Y 


U 


PC 



Relative 


Nanit 


Address 




SOO 


R$a 


SOI 


RSO 


M)\ 


R$A 


$02 


R$B 


$03 


R$I)R 


$04 


RSX 


$06 


RSY 


$0<S 


RSI.' 


■SUA 


RSPC 



Codes $25 through $27 and $70 through $7F are user-dc finable. 
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Set SWI 

OS9 F$SSWi 103F OE 

Function: 

Sets the interrupt vectors for SWI 2 and SWI3 instructions. 



ts 



Each process has its own local vectors. Bach Set SWI call set 
one type of vector according to the code number passed in 
Register A: 

1 - SWI 

2 - SWI2 

3 - SWI3 

When a process is created, all three vectors are initialized with 
the address of the OS-9 service call processor. 

Warning: Microware-supplied software uses SWI2 io call OS- 
9. If you reset this vector these programs cannot work. If you 
change all three vectors, you cannot call OS- e ) at all. 

Entry Conditions: 

A ^ SWI type code 

X = address of the user software interrupt routine 

Exit Conditions: 

None 

If error: 

CC - C bit set 

B = error code 
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Set Time 
OS9 F$stime 



103F 16 



Function: 

Sets the current system date/time and starts the system real-time 
clock. The date and time are passed in a time packet as follows: 



Relative 


Value 


Address 







year 


1 


month 


2 


dav 


3 


hours 


4 


minutes 


5 


seconds 



Entry Conditions: 

X = relative add 'res s of the time packet 

Exit Conditions: 

The system time and date are set. 

If error: 

CC - C bit set 

B = error code 
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Sleep 

OS9 F$sleep 103F oa 

Function: 

Turns off the calling process temporarily. 

If* Register X contains 0, the process is turned off" indefinitely 1 ' 
(until it receives a signal). This is a good way to wait tor a signal 
or interrupt without wasting CPU time. 

If Register X contains 1, the process is turned off for the 
remainder of its current time slice. The process is inserted into 
the active process queue immediately, and resumes execution 
when it reaches the front of the queue. If the process receives a 
signal, it "awakens 11 before the time has elapsed. 

If Register X contains an integer from 2 through 255, the 
process is turned off for the specified number of ticks, //. The 
process is inserted into the active process queue after n-1 ticks. 
It resumes execution when it reaches the front of the queue. If 
the process receives a signal, it awakens before the time has 
elapsed. 

Entry Conditions: 

X = sleep time (in ticks), or 

X -= (sleep indefinitely), or 

X = I (sleep for remainder of current time slice) 

Exit Conditions: 

X = sleep time minus the number of ticks that the 

process was asleep 

If error: 

CC = C bit set 

B = error code 
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Time 

OS9 F$time 103F 15 



Function: 

Returns the current system date and time in the form of a 6-byte 
packet (in binary). The packet is copied to the address passed in 
Register X. 



The packet looks 


like 


this; 


Relative 




Value 


Address 








1 




year 
month 


2 




day 


3 




hours 


4 




minutes 


5 




seconds 



Entry Conditions: 

X = address of the area to store the time packet 

Exit Conditions: 

time packet 

If error: 

CC - C bit set 

B = error code 
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Unlink 

OS9 F$unlink 103F 02 

Function: 

Unlinks (destroys) a module, if it is not being used by another 
process. 

Device driver modules that are being used and certain system 
modules cannot be unlinked. ROM modules can be unlinked; 
they cannot, however, be deleted from the module directory. 

Entry Conditions: 

U = address of the module header 

Exit Conditions: 

None 



If error: 




CC 


= C bit set 


B 


= error code 



Technical Function: 

1. Unlink tells OS-9 that the module is no longer 
needed by the calling process. 

2. OS-9 decrements the module's link count. 

3a. If the resulting link count is zero, OS-9 destroys the 
module. 

3b. If any other process is using the module, the mod- 
ule's link count cannot decrement to zero. There- 
fore, OS-9 does not destroy the module. 
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Wait 

OS9 F$wait 103F 04 



Function: 

Turns off the calling process until a child process ' 'dies' ' by 
executing an Exit system call, or by receiving a signal. The Wait 
call helps you save system time. 

The child's process ID and exit status are returned to the parent. 
If the child died because of a signal, the exit status byte (Regis- 
ter B) is the signal code. 

If the caller has several children, the caller is activated when the 
first one dies. Therefore, one wait system call is required to 
detect termination of each child. 

If a child died before the Wait call, the caller is reactivated 
almost immediately. If the caller has no children, Wait returns 
an error. 

(See the Exit system call for more information.) 

Entry Conditions: 

None 

Exit Conditions: 

A = deceased child process' s ID 

B = deceased child process' s exit status code 

If error: 

CC = C bit set 

B = error code 
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Write 

OS9 I$write 



103F 8A 



Function: 

Writes to the file or device associated with the path numher 
specified. 

The path must have been opened or created in the write or 
update access mode. Data is written to the file or device without 
processing or editing. If data is written past the present end-of- 
file, the file is automatically expanded. 

Entry Conditions: 

X = starting address of data to write 

Y = number of bytes to write 
A = path number 

Exit Conditions: 

Y — number of bytes written 

If error: 

CC = C bit set 

B = error code 
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Write Line 



OS9 I$writln 



103F 8C 



Function: 

Writes to the file or device associated with the path number 
specified. 

Write Line is similar to Write except it writes data until a 
carriage return character is encountered. Line editing is also 
activated for character-oriented devices, such as terminals and 
printers. The line editing refers to auto line feed, null padding at 
the end of the line, backspacing, line deleting, and so on. 

The path must have been opened or created in the write or 
update access mode. 

(For more information about line editing, see "\SCFMAN Line 
Editing Functions 1 ' in Chapter 6.) 

Entry Conditions: 

X = starting address of the data to write 

Y = maximum number of bytes to write 
A = path number 

Exit Conditions: 

Y = number of bytes written 

If error: 

CC = C bit set 

B = error code 
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Allocate 64 



OS9 F$all64 



103F 30 



Function: 

Dynamically allocates 64-byte blocks of memory by splitting 
pages (256 bytes) into four sections. 

OS-9 uses the first 64 bytes of the base page as a "page table." 
This table contains the MSB of all pages in the memory struc- 
ture. It Register X passes a value of zero, the call allocates a new 
base page and the first 64-byte memory block. 

Whenever a new page is needed, a Request Sysmem system call 
(FSsrqmem) executes automatically. The first byte of each 
block contains the block number. Routines that use Allocate 64 
call should not alter this byte. 

The diagram below shows how seven blocks might be allocated: 



Base Page 





Any Memory 
Page 






Any Memory 
Page 


Page Table 
(64 bytes) 




X 


Block 4 


X 


Block 1 

(64 bytes) 


X 


Block 5 
(64 bytes) 


X 


Block 2 
(64 byte) 


X 


Block 6 
(64 byte) 


X 


Block 3 
(64 byte) 


X 


Block 7 
(64 byte) 



Allocate 64 is a privileged system mode cali 
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Entry Conditions: 

X ■= base address of the page table: =~ the page 

table has not been allocated 

Exit Conditions: 

A = bloek number 

X = base address of the page (able 

Y — address of the bloek 

If error; 

CC = C bit set 

B - error code 
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Find 64 

OS9 F$find64 103F 2F 



Function: 

Returns the address of a 64-byte memory block. 

OS-9 used Find 64 to find process descriptors and path descrip- 
tors when given their block number. The block number may be 
any positive integer. 

Find 64 is a privileged system mode call. 

Pantry Conditions: 

X = address of the block 

A = block number 

Exit Conditions: 

Y = address of the block 

It error: 

CC = C bit set 

B = error code 
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I/O Delete 
0S9 F$iodel 



103F 33 



Function: 

Deletes the specified I/O module from the system, if the module 
is not in use. 

This system call is used mainly by IOMAN and may be of 
limited or no use for other applications. 

I/O Delete is a privileged system mode call. 

Entry Conditions: 

X — address of an 110 module 

Exit Conditions: 

None 

If error: 

CC - C bit set 

B = error code 

Technical Function: 

1 . Register X passes the address of a device descriptor 
module, device driver module, or file manager 
module. 

2. OS-9 searches the device table for the address. 

3. If OS-9 finds the address, it checks the module's 
use count. If the count is zero, the module is not 
being used; OS-9 deletes it. If the count is not zero, 
the module is being used; OS-9 returns an error. 
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I/O Queue 
OS9 F$ioqu 



103F 2B 



Function: 

Inserts the calling process into the I/O queue of the specified 
process and puts the calling process to sleep indefinitely. 

It is assumed that routines associated with the specified process 
will send a wakeup signal to the calling process. 

I/O Queue is a privileged system mode call. 

Entry Conditions: 

A = process number 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B — error code 
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Insert Process 



OS9 F$aproc 



103F 2C 



Function: 

Inserts a process into the active process queue so that the process 
may be scheduled for execution. 

All processes already in the queue are sorted by process "age/ 1 
Age is a count of how many process switches have occurred 
since the process's last time slice. When a process is moved to 
the active process queue, its age is set according to its priority — 
the higher the priority, the higher the age. 

An exception is a newly active process that was deactivated 
while in the system state. Such a process is given higher priority 
because it usually is executing critical routines that affect shared 
system resources. 

Insert Process is a privileged system mode call. 

Entry Conditions: 

X = address of the process descriptor 

Exit Conditions: 

None 



If error: 




CC 


-= C bit set 


B 


= error code 
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Next Process 



OS9 F$nproc 103F 2D 

Function: 

Takes the next process out of the active process queue and 
executes it. 

If there is no process in the queue, OS-9 waits for an interrupt, 
and then checks the queue again. 

Next Process is a privileged system mode call. 

Entry Conditions: 

None 

Exit Conditions: 

Control does not return to caller. 



Request Sysmem 



OS9 F$srqmem 103F 28 

Function: 

Allocates a block of memory of the specified size from the top of 
available RAM. The size request is rounded to the next page 
boundary. 

Request Sysmem is a privileged system mode call. 

Entry Conditions: 

D - byte count 

Exit Conditions: 

LI — starting address of the memory area 

If error: 

CC -= C bit set 

B = error code 
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Return 64 



OS9 F$ret64 



103F 31 



Function: 

Deallocates a 64- byte block ol" memory. (See the Allocate 64 
system call for more information.) 

Return 64 is a privileged system mode call. 

Entry Conditions: 



X 


addrc 


\s\v of the 


' base 


pai*v 


A 


block number 






Exit Conditions: 










None 










If error: 










CC 


C bit 


set 






B 


error 


code 
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Return Sysmem 



OS9 F$srtmem 103F 29 

Function: 

Deallocates a block of contiguous pages. 

Return Sysmem is a privileged system mode call. 

Entry Conditions: 

U = start i Hi* address of memory to return: must 

point to an even page boundary 

D — number of bytes to return 

Exit Conditions: 

None 

If error: 

CC = C bit set 

B = error code 
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SET IRQ 

OS9 F$irq 103F 2A 



Function: 

Adds a device to or removes it from the IRQ polling table. 

This system call is used mainly by device driver routines. {See 
1 interrupt Processing* " in Chapter 2 for a complete discussion 
of the interrupt polling system.) 

Packet Definitions: 

Flip Byte Selects whether the bits in the device status 

register indicate active when set or active 
when cleared. If a bit in the flip byte is set, it 
indicates that the task is active whenever the 
corresponding bit in the status register is clear 
(and vice versa). 

Mask Byte Selects one or more bits within the device 

status register that are interrupt request 
flag(s). One or more set bits identify which 
task or device is active. 

Priority The device priority number: = lowest, 255 

= highest 

Set IRQ is a privileged system mode call. 

Entry Conditions: 

X — to remove a device, or 

X — address of a packet to add a device 

[x] = flip byte 

fx 4- I ] = mask byte 

[X + 21 - priority 
U = address of the service routine's memory area 

Y = address of die device IRQ service routine 

D — address of die device status register 

Exit Conditions: 

None 

If error: 

CC - C bit set 

B — error code 
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Verify Module 



OS9 F$vmodul 103F 2E 

Function: 

Checks the module header parity and CRC bytes of a module. 

If these values are valid, OS-9 searches the module directory for 
a module that has the same name. If one exists, OS-9 keeps the 
module that has the higher revision level. 

Verify Module is a privileged system mode call. 

Entry Conditions: 

X = address of the module to verify 

Exit Conditions: 

U = address of the module directory entry 

If error: 

CC = C bit set 

B = error code 
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Appendix A / Alphabetical System 

Call Lists 

User and I/O System Calls 



Name 




Call 


Purpose 


Code 


Allocate 


Bits 


FJktllbit 


Allocate in a bit map 


13 


Attach 




I$attach 


Attach a new device to the 
system 


SO 


Chain 




Rkhain 


Load and execute a new 
primary module 


05 



Change ISchgdir Change the v\orking director) 86 
Directory 

Close Path ISclose Close a path to a tile device 81 - 

Compare Names L$cmpnam Compare two names I 1 



CRC 


FScrc 


Compute the CRC 1 


17 


Create File 


I$create 


Create a path to a new file 


S3 


Deallocate 
Bits 


F$delbit 


Deallocate in a bit map 


14 


Delete File 


fSdelete 


Delete a file 


87 


Detach Device 


ISdetaeh 


Remove a de\ ice from the 
system 


SI 


Duplicate Path 


LSdup 


Duplicate a path 


82 


Exit 


F$exit 


Terminate the calling process 


Ob 


Fork 


F$tbrk 


Create a new process 


03 


Get ID 


FSid 


Get a process ID user ID 


OC 


Get Status 


I$getstt 


Get file device status 


8D 


Intercept 


FSicpt 


Set up a signal intercept 
trap 


09 


Link 


F&link 


Link to a memory module 


00 


Load 


F$load 


Load module(s) from a file 


01 


Make Director} 


ISmukdir 


Make a new directory 


85 


Memory 


F$mem 


Set the memory si/e 


07 


Open Path 


iSopen 


Open a path to a file/ device 


84 


Parse Name 


F$prsnam 


Parse a path name 


10 


Print Krror 


F$perr 


Print error message 


OF 


Read 


I$read 


Read data from a file device 


89 


Read Line 


I$readln 
FSschbit 


Read a text line with editing 


SB 


Search LJ its 


Search the bit map tor a 
free area 


12 
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User and I/O System Calls 



Name 


Call 


Purpose 


Code 


Seek 


ISseek 


Reposition (he logical file 
pointer 


88 


Send 


lSseiul 


Send a signal to another 
process 


08 


Set Priority 


F$sprior 


Set the process priority 


OD 


Set Status 


ISsetstt 


Set the tile device status 


8E 


Set SVC 1 


F^ssvc 


Install a function request 


32 


Set SWI 


FSssui 


Set an SWI vector 


0E 


Set Time 


KSstime 


Set the system date and time 


16 


Sleep 


FSsleep 


Put the calling process 
to sleep 


0A 


Time 


PStime 


Get the system date and time 


15 


Unlink 


FSunlink 


Unlink a module 


02 


Wait 


I $ wait 


Wait for a child process 
to die 


04 


Write 


iSwrite 


Write to a file device 


HA 


Write Line 


FWritln 


Write a line of text with 
editing 


8C 



System Mode System Calls 



Name 


Call 


Purpose 


Code 


Allocate 64 


F$all64 


Allocate a 64-byte memory 


30 


Find 64 


FSfind64 


Find a 64-byte memory block 


2F 


I'O Delete 


PSiodel 


Delete an I'O device from 
the system 


33 


I/O Queue 


PSioqu 


Insert a process into the 
I () queue 


2B 


Insert Process 


FS up roe 


Insert a process into the 
active process queue 


2C 


Next Process 


FSnproe 


Start the next process 


2D 


Request Sysmem 


FWqmem 


Request system memory 


28 
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System Mode System Calls 



Code Name 


Call 


Purpose 




Return 64 


I ; Sret64 


Deallocate (return) a 
64-byte memor\ block 


31 


Return Sysmem 


FSsrtmem 


Return sWem memory 


2 l ) 


Set IRQ 


I ; S»irq 


Add or remove a de\ ice from 
the IRQ tables 


2 A 


Verify Module 


KSvmodul 


Verify a module 


2E 
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Appendix B / Numerical System 

Call Lists 

User and I/O System Calls 



Code 


Name 


Call 


Purpose 


00 


Link 


FSlink 


Link to a memory module 


01 


Load 


FSload 


Load module(s) from a file 


02 


Unlink 


FSunJink 


Unlink a module 


03 


Fork 


FSfork 


Create a new process 


04 


Wait 


F$wait 


Wait for a child process to die 



05 



06 
07 
OS 



Chain 



Lxit 



Memory 



F$chain 



Load and execute a new primary 
module 



F.Vwit 



Terminate the calling process 



FSmem 



Set the memory si/e 



Send 



FSsend 



Send a signal to another 
process 



09 

0A 

0C_ 

0D 

OF 

OF 

10 

II 



intercept 



FSiept 



Set up a signal intercept trap 



Sleep 



FSsleep 



Put the calling process to sleep 



Get ID 



F.Sid 



Get a process II) user II) 



Set Priority 



FSsprior 



Set the process priority 



Set SVVI 



F$sswi 



Set an SWI vector 



Print Frror 



F$perr 



Print error message 



Parse Name 



F$prsnam 



Parse a path name 



Compare 
Names 



FScmpnam 



Compare two names 



12 



Search Bits 



F$schbit 



Search the hit map for a free 
area 



13 
14 



Allocate Bits 



FSallhit 



Allocate in a bit map 



\5 
16 
17 
32 
SO 



Deallocate 
Bits 



Time 



F$dclbit 



Deallocate in a bit map 



FStime 



Get the system date and time 



Set Time 



FSstijnc 



Set the system date and time 



Crc 



[•Vrc 



Compute the CRC 



Set SVC 1 



F$ss\c 



Install a function request 



Attach 
Device 



ISattaeh 



Attach a new device to the 
system 



81 



Detach 
Device 



ISdelach 



Remove a device from the 
system 
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User and I/O System Calls 



Code Name Call Purpose 



82 


Duplicate 
Path 


ISdup 


Duplicate a path 


83 


Create File 


l$create 


Create a path to a new file 


84 


Open Path 


I So pen 


Open a path to a file device 


85 


Make 
Directory 


ISmakdir 


Make a new director) 


86 


Change 
Director) 


ISchgdir 


Change the working directory 


87 


Delete File 


Ikleletc 


Delete a file 


88 


Seek 


iWk 


Reposition the logical file 
pointer- 


89 


Read 


I$rcad 


Read from a file 'device 


8A 


Write 


I $ write 


Write to a file 'device 


8B 


Read Line 


iSreadln 


Read a text file with editing 


8C 


Write Fine 


1$ writ In 


Write a line of text with 
editing 


8D 


Get Status 


I$getstt 


("Jet the file/device status 


8E 


Set Status 


ISsetstt 


Set the file-device status 


8F 


(lose Path 


iSclose 


Close a path to a file/device 
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System Mode System Calls 



Code 


Name 


Call 


Purpose 


2A 


Set IRQ 


F$irq 


Add or remove a device from 
the IRQ tables 


2B 


I/O Queue 


F$ioqu 


Insert a process into the I/O 
queue 


2C 


Insert 


F$aproc 


Insert a process into the 




Process 




active process queue 


2D 


Next Process 


F$nproc 


Start the next process 


2F 


Verify 
Module 


FSvrnodi.il 


Verify a module 


2F 


Find 64 


F$find64 


Find a 64- byte memory block 


28 


Request 
Sysmem 


F$srqmem 


Request system memory 


29 


Return 
Sysmem 


FSsrtmem 


Return system memory 


30 


Allocate 64 


F$all64 


Allocate a 64- byte memory 
block 


31 


Return 64 


F$ret64 


Deallocate (return) a 64- byte 
memory block 


33 


I/O Delete 


F$iodel 


Delete an I/O device from the 
system 
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Appendix C / Memory Module 

Diagrams 

Executable Memory Module Format 



Relative 
Address 




Use 




Check 
Range 






$00 
SOI 




Sync Bytes ($87CD) 





header 
parity 




$02 
$03 


r— 


Module Si/e (bytes) 






$04 
$05 





Module Name Oil set 






S06 


Type 


Language 




$07 


Attributes 


Revision 




$08 


Header Parity Check 




CRC 


$09 
$()A 




Pxecution Offset 









SOU 

$oc 


— 


Permanent Storage Si/e 







$0D 




(Additional optional header- 
extensions located here) 








Module Body 

object code, constants. 

and so on 









CRC Cheek Value 
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Device Descriptor Format 



Relative 
Address 



Ise 



Cheek 
Range 



$00 
$01 






S\nc levies ($N7CD> 





$02 
$03 







Module Size 





$04 
$05 







Offset to Module Name 





S06 




$]■ 


(Type) 


SI (Lang) 


$07 




At 


ribules 


Re\ ision 


$08 


Header Parity Check 


$09 
SOA 







Offset to Pile Manager 
Name String 





SOB 






Offset to Device Driver 

Name String 





$0D 


Mode Byte 


$0R 
SOP 

$10 







Device Control lei 

Absolute Physical Addr. 

(24 bit) 





ill 


Initialization Table Si/e 


$12.$I2 + // 


{Initialization Table) 




(Name Strings, and so on) 




CRC Cheek Value 



header 

parity 



module 
CRC 
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INIT Module Format 



Relative 

Address 



Use 



Check 
Range 



$00 

$01 
$02 

$03 
$04 

$05 
$06 
$07 
$08 
$09 

$0A 
SOB 

$0C 

$00 

$E 



$0F 

$10 

$11 
$12 

$13 
$14-n 



Sync Bytes (S87CD) 



Module Size (h>tes) 



Module Name Of] set 



$L (Type) 



Attributes 



$1 (Lang) 



Revision 



Header Parit\ Check 



Forced Limit of" Top 
of free RAM 



#IRQ Polling Tabic Lntries 



# Device Table Lntries 



Offset to Startup 
Module Name String 



Offset to Default Mass 
Storage Device Name String 



Offset to Bootstrap 

Module Name Striim 



Name Strings 



CRC Check Value 



header 
parit) 



module 
CRC 
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Appendix D / Standard Floppy 

Disk Format 

TRS-80 Color Computer 

Physical Track Format Pattern 



Format 


Bytes 


Value 




(Dec) 


(Hex) 


Header pattern 


32 


4H 


(once per track) 


12 


00 




3 
1 


\ : 5 




32 


4h 


Sector pattern 


K 


00 


(repeated 18 times) 


3 
1 
1 
1 
1 


F5 

tracknumber (0-34) 
side number (0) 
sector number (1-18) 
sector length code ( 1 ) 




i 


CRC 




22 


4F 




12 


00 




3 
1 


F5 
FB 




256 


data area 




o 


CRC 




24 


4F 


Trailer pattern 


N 


4H (till to index mark) 


(once per track) 
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Appendix E / System Call Error 

Codes 



The error codes are shown in both hexadecimal (first column) and decimal (second column). 
Error codes other than those listed are generated by programming languages or user programs. 



Dec Hex Message 



Meaning 



200 %CX PATH TABU: LULL 



The file cannot be opened 
because the system path 
table is lull. 



2U1 $C9 



LLLGAL PATH NUMBLR 



The number is too large or 
is for a nonexistent path. 



202 SCA INTKRRUPT POLLING 

tabu; LULL 

203 SCB 1LLLGAL MODI; 



You can't add an interrupt. 



You tried to perform an I () 
function o\ which the device 
or file is incapable. 



204 


sec 


DHVICL TABLH LULL 


You eaift add a device. 




205 


SUD 


1LLLGAL MODULL 
HLADLR 


The module is not loaded; its 
sync code, header parit\ . or 
URU is incorrect. 




206 


set; 


MODULI- DIRECTORY 
IT'LL 


\'ou can't add a module. 




207 


$CL 


mlmory pull 


There is not enough 
contiguous RAM lice. 




208 


$1)0 


ILLLGAL SLRY1UL 
RLQULST 


The system call contains an 
illegal code number. 




209 


SDI 


moduli; busy 


The module is nou-sharahle 
and is being used In another 
process. 




210 


SD2 


BOUNDARY LRROR 


The memory allocation or 
deallocation request is not 
on a page boundary . 





211 SD3 LNDOPL1LL 



The end of the tile v\ as 
encountered on a read. 



:i2 SI)4 NOT YOUR MLMORY 



You tried to deallocate 
meniorv that was not assigned. 



2u SD5 non-l:xisting slgmlnt 



The device's file structure 
is damaged. 



:\4 SD6 in u; not agclssibll 



21 .S SD7 BAD PATH NAMH 



The file attributes do not 
permit the access requested. 

The pathlist eoulamed a 
syntax ciror possiblv 
an illegal character 
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Dec Hex Message 



Meaning 



216 SD8 (ILL NOT I OLND 



The specified pathhst does 
mil exist. 



217 SI) 1 ) SLGMLNT LIST IT'LL 



The file is too fragmented to 
be expanded 



2IS SDA l ; ILH ALRLADY LX1STS 



The specified filename 
ahead) exists in the current 
directors'. 



219 


SDH 


ILLLGAL BLOCK 


The device's file struct Lire 






ADDRLSS 


is damaged. 


220 


SDC 


ILLLGAL BLOCK SIZL 


The de\ ice's file structure 
is damaged. 



221 SDD MODLLL NOT FOUND 



You tried to link to a 
module that is not in the 
directory. 



222 SDL SLCTOR OUT Ol RANGL 



The device's file structure 
is damaged or incorrectly 
formatted. 



223 SDL SUICIDL ATTLMPT 



Vou tried to return the 
memory that contains your 
stack. 



224 


SLO 


ILLLGAL PROCLSS 
ID NUMBLR 


The specified process does 
not exist. 




226 


SL2 


NO CHILDRLN 


The process can't do a Wait 
because it has no children. 




227 


SL3 


ILLLGAL SWI CODL 


The code must be from I to 3. 





22X SL4 KLYBOARD ABORT 



229 SL5 PROCLSS TABLL LULL 



The process was aborted by 
Signal Code 2. 



The process can't do a fork 
now. 



230 SL6 ILLLGAL PARAMLTLR 

ARLA 



The high and low bounds 
passed in lank call are 
incorrect. 



231 SL7 KNOWN MODULH 



This module is for internal 
use only. 



232 $B8 1NCORRLCT CRC 



The module has a bad CRC 
value. 



233 %E9 SIGNAL LRROR 



The receiving process has 
a previous, unprocessed 
signal pending. 



234 SLA NONLXISTLNT MODULL 



The specified module does 
not exist. 
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Dec 


Hex 


Message 


Meaning 


235 


$EB 


BAD NAME 


The name uses an illegal 
syntax. 


236 


SEC 


BAD HEADER 


The module header parity 
is incorrect. 


237 


$ED 


RAM FUEL 


There is no free system RAM 
at this time. 


238 


$EE 


BAD PROCESS ID 


The process ID is incorrect. 


239 


$EF 


NO TASK NUMBER 
AVAILABLE 


All task numbers are in use. 


240 


$F() 


UNIT ERROR 


The device unit does not 
exist. 


241 


$FT 


SECTOR ERROR 


The sector number is out ot 

range. 


242 


SF2 


WRITE PROTECT 


The device is write 

protected. 


243 


$F3 


CRC ERROR 


A CRC error occurred on a 
read or write verily. 



244 



$E4 



READ ERROR 



249 $F9 WRONG TYPE 



A data transfer error 
occurred during a disk read 
or an SCE (terminal) input 
buffer overrun. 



245 


$F5 


WRITE ERROR 


A hardware error occurred 
during a disk write. 


246 


$F6 


NOT READY 


The device has the "not 
ready" status. 


247 


$F7 


SEEK ERROR 


You attempted a physical seek 
to a nonexistent sector. 


248 


$F8 


MEDIA FULL 


The media does not contain 
enough free space. 



You tried to read an 
incompatible media, such as a 
double-sided disk on a 

single-sided drive. 



250 $FA DEVICE BUSY 



A non-sh arable device is in 
use. 
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Appendix F / Module and I/O 

Attributes 



Standard I/O Paths 




Module I 


.unguages 


$00 - Standard In 


IpLlt 


$00 


Data 


$01 = Standard C) 


Lltput 


$01 


(>X0 l ) Object Code 


$02 - Standard hi 


rror Output 


$02 


BASIC (W l-Code 






$03 


Pascal P-Code 






$04 


Cobol l-Code 


File Access Codes 




Module 1 


l> pes 


$01 - Read 




$01 


Program Mntlulc 


$02 - Write 




$02 


Subroutine Module 


Read -f Write - V 


pdate 


$03 


Mullt Module 


$04 - L:\cc 




$04 


Data Module 


$08 - PRcad 




$0C 


System Module 


$10 - PWrite 




$01) 


Pile Manager 


$20 -- PPxec 




$01: 


Device Drivei 


$40 = Share 




SOP 


Device Descriptor 


$<S0 - Hii- 








Module Attributes 








$8 - Reentrant 
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INDEX 



Access codes 111, 167 

Active process 11,12 

Active state 1 1 

Age 12 

Allocate 64 (F$ail64) 136-137 

Allocation bit map 8 

see Bit map 
Assembly-language programming 67-73 

Addressing variables and data structures 68 

Extended addressing 68 

Interrupt-driven device drivers, parts 70 

Interrupt-driven device drivers, writing 70-71 

Interrupt masks 69 

Position-independent code, how to write 67 

Rules for writing 67 

Sample program 72-73 

Stack requirements 69 

Standard I/O paths, using 69 
Attach (l$attach) 80 



B 



Bit map 8 

Clearing bits in (F$delbit) 90 

Searching for a free block (F$schbit) 118 
Boot 3 
Bootstrap module 3 

see Boot 



Chain (F$chain) 82-83 
Change Directory (l$chgdir) 84 
Character-by-character I/O (SCFMAN) 2, 27, 53-65 
Child process 10 

Creating (F$fork) 95 
Clearing bits in allocation bit map (F$delbit) 90 
Clock module 2 
Close Path (l$close) 85 
Commands, interpreting (Shell) 3 
Compare Names (F$cmpnam) 86 
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INDEX 



CRC (F$CRC) 87 

CRC byte, checking (F$vmodul) 147 

CRC value 87 

Create File (l$create) 88 

Cyclic redundancy count, calculating (F$crc) 87 

CWAI instruction 12 



Date 129, 131 

Returning (F$time) 131 

Setting (F$stime) 129 
Deallocate bits (F$delbit) 90 
Delete File (l$delete) 91 
Detach Device (l$detach) 92 
Device 80, 92, 99-102, 111-112, 122-125 

Adding to or removing from IRQ polling table 
(F$irq) 146 

Attaching a new (l$attach) 80 

Detaching (l$detach) 92 

Opening a path to (l$open) 111-112 

Parameters, handling (l$getstt and l$setstt) 
99-102, 122-125 

Status, returning (l$getstt) 99-102 

Status, setting (l$setstt) 122-125 

Table 26 

Verifying (l$attach) 80 

Writing to (l$write) 134 

Writing to with editing (l$writeln) 135 
Device descriptor module 3, 28-30, 39-40, 57-58 

Format of 30, 158 
Device driver module 3, 27-28, 40-41, 58 

Branch table 28 
Directory 37 

Changing the working directory (l$chgdir) 84 

Creating and initializing (l$makdir) 108 
Disk allocation map sector (LSN 1) 34 
Disk file 

see File 
Disk I/O (RBFMAN) 2, 27, 33-52 
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INDEX 



Editing 

see Line Editing Functions 53-54 
Error message 115, 163-165 

Writing (F$perr) 115 
Exit (F$exit) 94 



File 2, 8, 14, 26-27, 35-35, 88, 91, 99-102, 111-112, 

122-125, 135 

Creating and opening (l$create) 88 

Deleting (l$delete) 91 

Opening a path to (l$open) 11-112 

Pointer, repositioning (l$seek) 119 

Status, returning (l$gttstt) 99-102 

Status, setting (l$setstt) 122-125 

Terminating path to (l$close) 85 

Writing to (l$write) 134 

Writing to with editing (l$writln) 135 
File access codes 1 1 1 
File descriptor sector 35-36 
File manager module 2, 26-27 

see also RBFMAN, SCFMAN, and PIPEMAN 
Find 64 (F$find64) 138 
Firq interrupt 14 
Fork (F$fork) 10, 95 

Free block, searching bit map for (F$schbit) 118 
Free memory 8 
Function calls 7, 75 



Get ID (F$id) 98 

Get Status (l$gttstt) 99-102 



171 



INDEX 



H 

Header 19-21 

Sync Bytes 19 

Module size 19 

Offset to module name 20 

Type/language byte 20 

Attributes/revision byte 21 

Header check 21 

Execution offset 23 

Permanent storage size 23 
Hexadecimal number iv 

I 

ID, returning (F$id) 98 
Identification sector (LSN 0) 34 
IIMIT2, 5, 159 
Input/output manager 2, 26 

see IOMAN 
Insert Process (F$aproc) 141 
Intercept (F$icpt) 103 
Intercept trap, setting (F$icpt) 103 
Interrupt processing 14-16 
Interrupt vectors, setting for SWI2 and SWI3 
instructions 

(F$sswi) 128 
(OMAN 2, 26 
I/O 2-3, 25, 27-28, 40-41, 53-65, 69 

Character-by-character (SCFMAN) 2, 27, 53-65 

Modules 25 

Non-disk (SCFMAN) 2, 27, 53-65 

Paths, standard 69, 167 

Physical functions for specific I/O controller 
hardware (device driver module) 3, 27-28, 
40-41, 58 

System calls 6, 75, 149-150, 153-154 
I/O Delete (F$iodel) 139 

I/O port, associating with its logical name, device driver 
and file manager (device descriptor module) 3, 
28-30, 39-40, 57-58 
I/O Queue (F$ioqu) 140 
IRQ interrupt 15 
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INDEX 



IRQ polling table 15-16 

Adding to or removing from (F$irq) 16, 146 

Flip byte 15 

Mask byte 1 5 

Polling address 15 Priority 16 

Service routine address 16 

Static storage address 1 6 



K 



Kernel 2, 5-16 

Functions of 5 



Line editing functions 53-54 

Link (F$link) 104-105 

Load (F$load) 106-107 

Logical interrupt polling system 15-16 

Logical sector number 33 

LSN 34 

LSN 1 35 

M 

Make Directory (l$makdir) 108 
Memory 110 

Allocating automatically 8 

Allocating block from top of available RAM 
(F$srqmem) 143 

Deallocating block of contiguous pages 
(F$srtmem) 145 

Deallocating 64-byte block (F$ret64) 144 

Dynamically allocating 64-byte blocks (F$all64) 
136-137 

Size, setting (F$mem) 110 
Memory (F$mem) 110 
Memory management, advantages of 7 
Memory map 9 
Memory module iii, 1 

see Module 
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INDEX 



Module iii, 1 

Attributes 17, 167 

Deleting an I/O module (F$iodel) 139 

Executable memory module format 22, 157 

Format (parts) 18-19 

Languages 20, 167 

Linking to (F$link) 104-105 

Loading and executing (F$chain) 82-83 

Loading from a file (F$load) 106-107 

Loading from the working executing directory 
(F$load) 

106-107 

ROM 23-24 

Types 17, 167 

Unlinking (F$unlink) 132 
Module body 19 
Module CRC value 19 
Module header 18 

See Header 
Multiprogramming 9-13 

N 

Name 86, 113-114 

Analyzing a text string for (F$prsnam) 113-114 
Comparing names (F$cmpnam) 86 

Next Process (F$nproc) 142 

NMI interrupt 15 

Non-disk I/O (SCFMAN) 2, 27, 53-65 



Open Path (l$open) 111-112 
OS9Defs 75 



Page 8 

Parity byte, checking (F$vmodul) 147 

Parse Name (F$prsnam) 113-114 
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INDEX 



Path 

Duplicating (l$dup) 93 

Opening (l$open) 111-112 

Reading from (l$read and l$readln) 116,117 

Repositioning its logical file pointer (l$seek) 119 

Terminating (l$close) 85 
Path descriptor (PD) 31-32, 37-38, 54-56 

Standard information 31-32 
Path table 26 
Pipe file manager 2 
PIPEMAN 2 
Pipes 2-3 

Pointer, repositioning (l$seek) 119 
Primary module 10 
Print Error (F$perr) 115 
Priority 16 

Setting (F$sprior) 121 
Process 9 

Creating a new (F$fork) 10-11 

Inserting into I/O queue and putting to sleep 
(F$ioqu) 140 

Inserting into active queue for execution 
scheduling (F$aproc) 141 

Removing from active process queue and 
executing (F$nproc) 142 

Terminating the calling process (F$exit) 11, 94 

Turning off the calling process until child process 
dies (F$wait) 133 

Turning off the calling process temporarily 
(F$sleep) 130 
Process age 12 
Process descriptor 10 
Process ID 11 

Returning (F$id) 98 
Process priority, setting (F$sprior) 121 
Process states 11-12 

Q 

Queue 2 
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INDEX 



Random Block File Manager 2, 27, 33-52 

see RBFMAN 
RBFDefs 32 
RBFMAN 2, 27, 3-52 
Read (l$read) 116 
Read Line (l$readln) 117 
Real-time clock 10 

Starting (F$stime) 129 
Request Sysmem (F$srqmem) 143 
Return Sysmem (F$srtmem) 145 
ROM modules 23-24 
Root directory 37 
RTI instruction 13, 16 
RTS instruction 13, 16 



SCFDefs 32 
SCFMAN 2, 27, 53-65 

Line editing functions 53-54 
Search Bits (F$schbit) 118 
Seek (l$seek) 119 
Send (F$send) 13, 120 
Sequential Character File Manager 2, 27, 53-65 

see SCFMAN 
Set IRQ (F$irq) 146 
Set Priority (F$sprior) 121 
Set SVC (F$ssvc) 126-127 
Set Status (l$setstt) 122-125 
SetSWI (F$sswi) 128 
Set Time (F$stime) 129 
Shell 3 

Sleep (F$sleep) 12, 130 
Sleeping state 12 
Signal 12-13 

Codes 13 

Intercept trap, setting (F$icpt) 13 

Sending (F$send) 120 
String 

Analyzing for legal OS-9 name (F$prsnam) 
113-114 

Comparing strings (F$cmpnam) 86 



176 



INDEX 



SWI interrupt 14 
SWI2 interrupt 14 

Setting interrupt vectors for (F$sswi) 128 
SWI3 interrupt 14 

Setting interrupt vectors for (F$sswi) 128 
SYSGO 5 
System call 6, 75 

Adding or replacing (F$ssvc) 126-127 

Lists 75, 149-155 

Processing 5, 6-7, 76-77 

Types 6-7 
System initialization 5 
System mode calls 76 
System startup task (SYSGO) 5 



Tick 10 

Time 10, 19, 131 

Returning (F$time) 131 

Setting (F$stime) 129 

Slice 10 

U 

Unix operating system iii 
Unlink (F$unlink) 132 
User calls 149-150, 153-154 
User ID 11 

Returning (F$id) 98 
V 

Vectors 14 

Hardware 14 

Setting for SWI2 and SWI3 instructions (F$sswi) 
14, 128 
Verify Module (F$vmodul) 147 
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INDEX 



w 



Wait (F$wait) 133 

Waiting state 5, 1 1 

Western Digital Floppy Disk Controller IC 39 

Wildcard calls 99-102, 122-125 

Working directory 84 

Changing (l$chgdir) 84 
Write (l$write) 134 
Write Line (l$writeln) 135 
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This addendum introduces the changes and new features of 
OS-9, Version 02.00.00. Some of the information is technical 
and is only of interest to programmers. However, other fea- 
tures of the new OS-9 Version 02.00.00 are of interest to all 
system users. 
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Section 1 / Commands and Utilities 



CONFIG 



CONFIG provides menus of all I/O options and all system 
commands. You select the device drivers and commands you 
want to include on a new system diskette from these menus. 
Selecting only the device drivers and commands you and 
your system require lets you make the most efficient use of 
computer memory and system diskette storage. 

The CONFIG utility is on a separate CONFIG/BOOT 
Diskette. Make a copy of this diskette using the OS-9 
BACKUP command and use the copy as your working 
diskette. Keep the original CONFIG/BOOT Diskette in a safe 
place to use for future backups. You can use the CONFIG/ 
BOOT Diskette for booting OS-9 from Color Disk BASIC 
from Drive /D0. 

CONFIG requires no initial parameters. You establish param- 
eters during the operation of CONFIG. Be sure that the exe- 
cution directory is at /D0/CMDS before executing the 
command. 

Examples: 



CONFIG [ENTER 



CONFIG executes and a prompt asks you to indicate whether 
you wish to use one or two disk drives. Press [Tj for single- 
or [T] for two-drive operation. 

Next, CONFIG builds a list of the various devices from the 
MODULES directory. When the list is complete, a screen 
menu appears. Use the up and down arrow keys to move to a 
device. Then, press [$] to either select or exclude a particu- 
lar device. Press [s] once to display an X to the right of the 
selected device. Press QT| again to erase the X. The device is 
selected only when "X" appears. Information about each 
device is available with a special help command. To display 
the information on the current device (the device indicated by 
the arrow ( -> ), press [17] . 



If there are more than ten devices in a CONFIG menu, 
[-*"] to move ahead page-by-page and [j^\ to move back. 

The devices you can select are; 



use 



term 32 


The computer keyboard and standard TV 




display 


term 80 


The computer keyboard and optional 80 




column video display 


d« 


Disk Drive 


dl 


Disk Drive 1 


d2 


Disk Drive 2 


d3 


Disk Drive 3 


H0-15 


A 15 meg hard disk drive 


hl-15 


A 15 meg hard disk drive 1 


h0-35 


A 35 meg hard disk drive 


hi -35 


A 35 meg hard disk drive 1 


P 


A printer using the RS-232 serial port 


tl 


A terminal port using the standard 




RS-232 port 


t2 


A terminal port using the optional 




RS-232 communications pak 


t3 


A terminal port using the optional 




RS-232 communications pak 


ml 


A modem 


m2 


A modem 


ssc 


Speech/Sound Cartridge 



To use your computer keyboard and video display, you must 
select one term. You must select d(D as your first disk drive. 
Select dl , c/2, and d3 for additional floppy disk drives. Select 
p to use a printer with OS-9, select ssc to use a Speech/ 
Sound Cartridge from a Multi-Pak slot, and so forth. 

After selecting the devices you desire, press QT|. The screen 
displays, ARE YOU SURE CY/N) ? If you are satisfied 
with your selections, press {T\. If you wish to make further 
changes, press [W] . 

When the driver selection is complete, a screen prompt 
requests that you select among the Color Computer terminal 
I/O subroutines. Select these subroutines in the same manner 
that you selected the device drivers. You have the following 
modules from which to make your selections: 



CQ32 A video output module lor a 32 column 

TV display 
CO80 A video output module for a 80 column 

video display 
GRFO A graphics module for TV display 

When choosing subroutine modules, you must select the 
video output module that matches the terminal module you 
previously selected for your console device. 

CONFIG builds a boot list from the selected devices and 
their associated drivers and managers. "BootHst" is created 
in the ROOT directory of Drive 0. CONFIG next displays 
two clock options: 

1 - 60hz (American) 

2 - 50hz (European) 

If you live in the United States, Canada, or other country 
with 60hz electrical power, press (jj. If you live in a coun- 
try with 50hz power, press (T). 

If you have a single disk drive, a screen prompt asks you to 
swap diskettes and press (IT). When asked to insert the 
SOURCE diskette, insert the CONFIG/BOOT Diskette. When 
asked to insert the DESTINATION diskette, insert the diskette 
on which you wish to create the new OS-9 System. 

If you have more than one drive, a screen prompt asks you to 
insert a blank formatted diskette (the DESTINATION diskette) 
in /Dl. The rest of the boot file creation is automatic. 

Following the boot file generation, a menu lets you select the 
commands you wish to include on your system diskette. You 
have the following choices; 

CNlo Commands, Stop Now 

— - Do not add any commands 
CB]asic Command Set 

— Add the basic OS-9 commands 
[FJull Command Set 

— Add all OS-9 commands 
[individually Select 

— Select desired commands one by one 



[?] Receive Help 

— Get help on the command set 

Press {W\ if you want to create a boot file, but do not wish to 
add any commands to the new system diskette. Use this 
option to create a new boot file on a diskette on which you 
have previously copied the OS-9 system. If you have only 
one disk drive, this procedure is quicker than using the CON- 
FIG utility to complete the entire system transfer, as less 
diskette swaps are required. 

Press (jT| if you wish to add a basic command set (the most 
commonly used commands) to your new diskette. This selec- 
tion does not copy the following: 

• Assembly language development tools, asm, debug, and 
edit and the DBFS directory 

• Timesharing utilities, tsmon, login and the SYS/motd and 
SYS/password Hies 

• The system maintenance utilities, such as dsavc, dcheck, 
and cobbler. 

Press (T] to copy all of the commands (an exact copy of the 
standard OS-9 system diskette, with a new boot file). 

Press (T) to individually select commands to copy on the new 
diskette. This option displays a selection similar to the device 
selection screen. Again, press (IT) to select or exclude com- 
mands, and use the arrow keys to move among the com- 
mands in the menu. Commands marked with an X are 
selected. If a command does not have an X beside it, it is 
excluded on the new system diskette. 

If you have a multi-drive system, a prompt appears asking 
you to insert your OS-9 system diskette in /DO. Press the 
spacebar. The process finishes the CONFIG operation and 
returns to OS-9. 

If you have a single-drive system, you swap diskettes during 
the final process. This time, the SOURCE diskette is the 
OS-9 System Diskette, instead of the CONFIG/BOOT 
Diskette. The DESTINATION diskette is the new system 



diskette you are creating. The number of swaps in this proce- 
dure, as well as in the boot file creation procedure, depends 
on the number of options you select. 

It would be quicker and easier to use BACKUP to create a 
system disk, use CONFIG to create a new boot file, then 
delete unwanted commands. However, this process causes 
fragmentation of diskette space. Fragmentation results in 
slower diskette access, and free memory is broken into seg- 
ments that might not be large enough for some OS -9 opera- 
tions. CONFIG causes no fragmentation. 

The MODULES directory of the CONFIG/BOOT diskette 
contains all the device drivers and descriptors supported by 
OS-9. The filename extension describes the type of file, as 
noted in the following table: 



Extension 


Module Type 


.dd 


Device Descriptor module 


.dr 


Device Driver module 


.io 


Input/Output subroutine module 


.h P 


Help file 



FORMAT 

FORMAT devname [R] [diskname] 



Initializes, verifies, and establishes an initial file structure on 
a diskette. You must format all blank diskettes before you can 
use them on an OS-9 system. 

Options: 

dev name is the drive name of the diskette you wish to 

format, D0 or Dl. 

R causes the format to proceed automatically, 

without displaying prompts. 

diskname is the name you wish to assign to the newly 

formatted diskette. The diskname must be 
enclosed in double quotation marks. 

Notes: 

Be sure the diskette you want to format is NOT write pro- 
tected. If a write -protect tab is in place, the system returns to 
the OS-9; prompt without formatting the diskette. 

The formatting process works this way: 

1. FORMAT physically initializes the diskette and organizes 
its surface into sectors. 

2. FORMAT reads back and verifies each sector. If FOR- 
MAT fails to verify a sector after several attempts, it 
excludes that sector from the initial free space on the 
diskette. As the verification proceeds, track numbers 
appear on the screen. 

3. FORMAT writes the diskette allocation map, ROOT 
directory, and identification sector to the first few sectors 
of track zero. These sectors must not be defective. 

At the prompt, type a diskette volume name. You can use as 
many as 32 characters, including spaces or punctuation. 
(Later, you can use the FREE command to display the 
name.) 



For step-by-step instructions on formatting, refer to Getting 
Started with OS -9. 

Examples: 



FORMAT /D1 ENTER 



formats a diskette in Drive 1 . 



FORMAT /D1 R "test disk" I ENTER ' 



formats the disk in Drive 1, with the name Test Disk, 



HELP 

HELP command name [ . . . ] 

Displays the usage and syntax of OS-9 commands. 

Options: 

command is the command for which you want syntax 

name help. Include as many command names in one 

HELP line as you wish. The proper form and 

syntax appears for each valid command you 

include. 

Notes: 

To use HELP, first copy Cmds.hp from the SYS directory of 
the CONFIG/BOOT diskette to the SYS directory of your 
system diskette. Next, copy HELP from the CMDS directory 
of the CONFIG/BOOT Diskette to the CMDS directory of 
your system diskette as follows: 

Procedure for one disk drive: 

1. With OS-9 booted and the system diskette in your drive, 
type: 



LOAD COPY ENTER 



2. Replace the system diskette with the CONFIG/BOOT 
Diskette, and type: 

COPY /D0/SYS/CMDS.HP 



/D0/SYS/CMDS.HP -S #30K ENTER 



3. Exchange the two diskettes as requested by the screen 
prompts until the process is complete. 

4. Again, place the CONFIG/BOOT Diskette in the drive, 
and type: 

COPY /D0/C MD5/h elp /D0 /CMDS/he 1 p 
-S #30K ( ENTER I 



5. Swap diskettes as requested until the process is complete. 



Procedure for two disk drives: 

1. With OS-9 booted, place the CONFIG/BOOT Diskette in 
Drive 1. Be sure the system diskette is in Drive 0. 

2. Type: 

COPY /D1 /SYS/CMDS.HP 



/D0/SYS/CMDS.HP [ENTER 



3. When the first copy is complete, type: 

COPY /D1 /CMDS/help 
/D0/CMDS/help | ENTER | 

Cmds.hp is a data file, not a text file, and you cannot suc- 
cessfully display it on your screen or edit it with a standard 
text editor. It contains help for standard OS-9 commands. 

HELP displays the form and syntax of the specified com- 
mand. If you use a non-standard command name, a screen 
display tells you that help is not available for that command. 

Examples: 



HELP BACKUP ( ENTER ! 



BACKUP [e] [5] t-v] [devl [dev] 
Copies all data from one device to another 



HELP ME I ENTER I 

ME Help not available 



HELP ENTER 



HELP [command nameH 



INIZ 

INIZ devicename [ 



Links the specified device to OS-9, places the device address 
in a new device table entry, allocates the memory needed by 
the device driver, and calls the device driver initialization 
routine. If the device is already installed, INIZ does not rein- 
itialize it. 



Options: 

devicename 

Notes: 



is the name of the device driver you want to 
initialize. Specify as many device drivers as 
you wish with one INIZ command. 



You can use INIZ in the startup file or at the system startup 
to initialize devices and allocate their static storage at the top 
of memory (to reduce memory fragmentation). 

Example: 



INIZ P T2 ENTER 



initializes the P (printer) and T2 (terminal 2) devices. 
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0S9GEN 

OS9GEN devname [-s] [#«K] 



Creates and links the required OS9Boot file on any diskette 
from which you wish to boot OS -9. 



Options: 

devicename 



-s 



#/7K 



is the disk drive containing the diskette on 
which you wish the new boot file to be 
created . 

causes OS9GEN to perform a single-drive 
boot file generation operation. In a single- 
drive operation, OS9GEN reads the mod- 
ules from the source diskette and requests 
that you exchange diskettes and press (IT) as 
the modules are read and copied. 

reserves n kilobytes of memory for use by 
the OS9GEN command. By setting aside as 
much memory as possible, you can increase 
the speed of OS9GEN and, on single-drive 
systems, lessen the number of diskette 
swaps. 



Notes: 



OS9GEN adds modules to an existing boot file, or creates a 
new one. (If you want an exact copy of the existing 
OS9Boot, you can also use COBBLER). 

OS9GEN creates a working file called tempboot on the 
device specified by devname. Next, it reads filenames (path- 
names) from its standard input (the keyboard), one pathname 
per line. OS9GEN opens each file and copies it to tempboot. 
The process repeats until it reaches an end-of-file marker or a 
blank line. All boot files must contain the OS-9 component 
modules listed in Section 5.1 of the OS-9 Commands 
manual. 

With all input files copied to tempboot, OS9GEN deletes the 
OS9Boot file, if it exists. Tempboot is renamed OS 9 Boot, 
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and its starting address and size are written in the diskette's 
Identification Sector (LSN 0) for use by the OS-9 bootstrap 
firmware, OS-9 writes its kernel on diskette Track 34. If 
there is not room for the 02.00.00 kernel, an error message 
displays and the operation terminates. 

An OS9Boot file must be in physically contiguous sectors. 
Therefore, you normally use OS9GEN on a newly formatted 
diskette. If the OS9Boot file is fragmented, OS9GEN prints a 
warning message indicating that you cannot use the diskette 
to bootstrap OS-9. 

You can either enter a list of filenames from the keyboard for 
OS9GEN or you can direct input to OS9GEN from a file 
containing a list of filenames. If you enter names manually, 
no prompts are given. Press [ ENTER j after typing each file- 
name. After typing the last filename and [ ENTER j , press 
( ENTER 1 again, or press [ CTRL ) [ BREAK [ to complete the list. 

If you have only one drive, you can more easily generate a 
new boot file using the CONFIG utility. CONFIG is 
designed to make custom system diskettes using either single- 
or multiple-drives. 

Examples: 



DS9GEN /D1 [ENTER 



/D0/OS9Boot [ENTER 



CTRL BREAK 



Manually installs a boot file on device /Dl that is an exact 
copy of the OS9Boot file on device /D0. The first command 
line runs OS9GEN. The second enters the name of the file to 
install, and the third enters an end-of-file marker. 



0S9GEN /D1 ENTER 



/D0/DS9Boot ENTER] 



/D0/tape. driver [ ENTER ] 
/D2/video . driver ( ENTER ] 
f CTRL II BREAK I 



Manually installs a boot file on device /Dl that is a copy of 
the OS9Boot file on device /D0 plus the modules stored in 
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the files /D0/tape. driver and /D2/video. driver. The first com- 
mand line runs OS9GEN. Line 2 enters the main boot file- 
name. Lines 3 and 4 enter the names of the two additional 
files, and Line 5 enters an end-of-file marker. 



BUILD /D0/bootlist ENTER I 



? /D0/QS9Boot (ENTER I 



? /D0/CMDS/DIR ENTER! 



? /D0/CMDS/COPY ENTER 



? ENTER 



QS9GEN /D1 </D0/bootlist rENTERl 



Generates a new boot file on Drive 1 that includes all the old 
boot file functions plus loads DIR and COPY into memory 
on startup. Line 1 uses BUILD to create a file called boot- 
list. The next three lines enter the names of the three files 
within bootlist. Line 5 terminates BUILD, and Line 6 runs 
OS9GEN with input redirected from the new bootlist file. 

To install a custom boot file on a single drive system, it is 
easiest to build a bootlist to drive the OS9GEN program. You 
also need a directory that contains the required file man- 
agers, device drivers, discriptors, and other files for the boot 
file. For example, to make a new boot file containing only 
/TERM, /D0 and i? devices, first build a bootlist such as: 



BUILD /D0/Bootlist [ENTER 



7 


I OMAN lENTERj 


7 


RBF ( ENTER j 


7 


CCDisk [ENTER) 


7 


D0 | ENTER] 


7 


SCF ( ENTER j 


7 


CCIO [ENTER] 


7 


TERM LENTERj 


7 


PRINTER [JNTERJ 


7 


P [ENTER J 


7 


CLOCK [ENTER] 


7 


SHELL [ENTER] 


7 


SYSGD [ENTERj 


7 


[ ENTER | 
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This procedure creates a bootlist on Drive in preparation 
for a single-drive OS9GEN operation. You must locate all of 
the files -in the current data directory by SAVEing the mod- 
ules from memory into the directory. Then, use OS9GEN to 
create the new boot file on a separate diskette by typing: 

DS9GEH /D0 -5 #25K 



</D0/Boot list ENTER 



This command causes OS9GEN to use only one drive, 25K 
buffer space, and the filenames previously stored in the 
bootlist file. 

You must have RENAME in the current execution directory 
or in memory for OS9GEN to work properly. 
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TMODE 

TMODE [.pathnum] [paramlist] [ . . . ] 



Displays or changes the operating parameter's of the 
terminal. 

Options: 

upc Displays uppercase characters only. Lower- 

case characters automatically convert to 
uppercase. 

-upc Displays both upper- and lowercase 

characters. 

bsb Causes backspace to erase characters. 

Backspace characters echo as a backspace- 
space-backspace sequence. This setting is 
the system default. 

-bsb Causes backspace not to erase. Only a sin- 

gle backspace echoes. 

bsl Enables backspaces over a line. Deletes 

lines by sending backspace-space-backspace 
sequences to erase a line (for video termi- 
nals). This setting is the system default. 

-bsl Disables backspace over a line. Lines are 

deleted by printing a new line sequence (for 
hard-copy terminals). 

echo Input characters echo back to the terminal. 

This setting is the system default. 

-echo Turns off the echo default. 

If Turns on the auto line feed. Line feeds 

automatically echo to the terminal on input 
and output carriage returns. This setting is 
the system default. 

-If Turns off the auto line feed default. 
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pause Turns on the screen pause. This setting sus- 

pends output when the screen is full. See 
the pag parameter for definition of screen 
size. Resume output by pressing the space 
bar. 

-pause Turns off the screen pause mode. 

null = /? Sets the null count, sets the number of null 

($00) characters transmitted after carriage 
returns for return delay. The number is in 
decimals. Default = 0. 

pag = n Sets video display page length to n (deci- 

mal) lines. This setting is used for pause 
mode. 

bsp = /? Sets the input backspace character and 

requires a hexadecimal value. Default = 
08. 

bse = /? Sets the output backspace character and 

requires a hexadecimal value. Default = 
08. 

del = /? Sets input delete line character and requires 

a hexadecimal value. Default = 18. 

bell = /j Sets the bell (alert) output character and 

requires a hexadecimal value. Default = 
07. 

cor = /i Sets the end-of-record (carriage return) 

input character. Requires a value in hexa- 
decimal. Default = 0D. 

cof—h Sets the end-of-file input character and 

requires a hexadecimal value. Default = 
IB. 
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type = /? For external devices, type is used for ACIA 

initialization values (hexadecimal). The 
default = 00. Bits 5-7 set either MARK, 
SPACE, or no parity on all devices. Codes 
for these are: 

= no parity 
101 = MARK parity transmitted, no 

checking 
111 = SPACE parity transmitted, no 
checking 

011 = even parity only available 
with the 

001 = odd parity external ACIA 
pak and 
Modpak devices. 

Bits 0-3 are reserved for future use. 

Bit 4 is used to select auto-answer modem 
support features. 

1 = on 

- off 

See Color Computer I/O Devices for 

further information. 

For TERM, the type byte has a different 

use: 

Bit specifies a machine with true 
lowercase capability. Set bit to turn 
on true lowercase. 

Bit 1 specifies output screen size. 
Clear bit 1 for 32 column output to 
the video screen. Set bit 1 for 80 col- 
umn output to the video screen 
through the 80 column card. 

reprint = h Sets the reprint line character and requires a 

hexadecimal value. 
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dup = h Sets the character to duplicate the last input 

line and requires a hexadecimal value. 

psc = // Sets the pause character. The numeric value 

of the character is in hexadecimal. 

abort ~h Sets the terminate character (normally 

CONTROL C). The numeric value of the 
character is in hexadecimal. 

quit = // Sets the quit character (normally CON- 

TROL L). The numeric value of the charac- 
ter is in hexadecimal. 

baud = /? Sets baud, word length, and stop bits rate 

for software-controllable interface. The 
numeric codes for baud rate are: = 6L, 
1 = 12C, 2 = 258, 3 = 4B0, 4-960, 
5=12C0, 6 = 2580, 7 = 4B00 in 
hexadecimal. 

Bits 0-3 determine the baud rate 
Bit 4 is reserved for future use 
Bits 5-6 determine the word length: 

00 = 8 bits 

01=7 bits 
Bit 7 determines the number of stop 

bits: 

0= 1 stop bit 

1 =2 stop bits. 

Notes: 

You can specify any number of parameters from the options 
list, separating them by spaces or commas. If you don't 
specify parameters, the output is determined by the current 
TMODL status. 

You can also use a period and a number to specify the output 
pathnumber. If you don't specify any, TMODE affects the 
standard input path. 

This utility adjusts its output for either an 80 or 32 column 
display. 
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If this command is used in a SHELL procedure file to 
change the terminal's operating characteristics, you must use 
the parameter .pathnum to specify one of the standard output 
paths (l=standard output, and 2 = standard error). The 
change remains in effect until the path closes. To make a 
permanent change to a device characteristic, change the 
device descriptor. 

TMODE works only if a path to the file/device is open. You 
can alter the device descriptor to set a device's initial operat- 
ing parameter using XMODE (see the OS-9 Commands 
manual). 

TMODE can also alter the baud, word length, stop bits, and 

parity for devices already initialized. 

Examples: 



TMODE -upc If null=4 pause [ ENTER 1 

TMODE pag-24 pause bsl 
-echo bsp-8 [ ENTER 1 

Note: If you use TMODE in a procedure file, it is necessary 
to specify one of the standard output paths (.1 or .2), 
because the SHELL'S standard input path is redirected to the 
diskette file. (You can use TMODE only on SCFMAN-type 
devices.) 

Example: 



TMODE . 1 pag = 24 | ENTER | 
This sets lines per page for standard output. 
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TUNEPORT 

TUNEPORT </P or /Tl> [s = value] 



Lets you test and set delay loop values for the current baud 
rate and select the best value for your printer (/P) or terminal 
(/Tl). 

Examples: 



TUNEPORT /P ENTER 



Provides a test operation for your printer. After a short delay, 
TUNEPORT displays the current baud rate and sends data to 
the printer to test if it is working properly. The program then 
displays the current delay value and asks for a new value. 
Enter a decimal delay value and press | ENTER [ . Again, test 
data is sent to the printer as a test. Continue this process 
until you find the best value. When you are satisfied, press 
[ ENTER 1 instead of entering a value at the prompt. A closing 
message displays your new value. 

Use the same process to set a new delay loop value for /Tl 
terminal. 



TUNEPORT /P -5-225 ENTER] 



Sets the delay loop value for your printer at 255. Use such a 
command on future system boots to set the optimum delay 
value determined with the TUNEPORT test function. Then, 
using OS9GEN or COBBLER, generate a new boot file for 
your system diskette. You can also use TUNEPORT in your 
system startup file to set the value using the -S option. 
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XMODE 

XMODE devname [paramlist] 



Displays or changes the initialization parameters of any SCF- 
type device such as the video display, printer, RS-232 port, 
and others. 

XMODE is commonly used to change baud rates and control 
key definitions. 

Options: 

upc Sets the screen display to uppercase only. 

Lowercase characters automatically convert 
to uppercase. 

-upc Sets the screen display to upper- and 

lowercase. 

bsb Causes a backspace to erase characters. A 

backspace character echoes as a backspace- 
space-backspace sequence. 

-bsb Turns off erase on backspace. Only a sin- 

gle backspace echoes. 

bsl Enables backspace over line function. Lines 

are deleted by sending backspace-space- 
backspace sequences. This option is for 
video terminals and is the default option. 

-bsl Disables backspace over line. Lines are 

deleted by producing a new line sequence 
(this option is for hard -copy terminals). 

echo Causes input characters to echo to the ter- 

minal. This is the default option. 

-echo Disables the echo function. 
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If Turns on the auto line feed. Line feeds 

automatically echo to the terminal on input 
and output carriage returns. This is the 
default option. 

-If Turns off the auto line feed. 

pause Turns on the screen pause mode. This set- 

ting suspends output when the screen is 
full. See pag parameter for definition of 
screen size. Resume output by pressing any 
key. 

-pause Turns off the screen pause mode 

null — // Sets the null count, the number of null 

characters ($00) transmitted after a carriage 
return. The number is a decimal value. 
Default - 0. 

pag — // Sets video display page length to n (deci- 

mal) lines. This setting is used for pause 
mode. 

bsp = // Sets the input backspace character and 

requires a hexadecimal value. Default = 
08. 

bse = /? Sets the output backspace character and 

requires a hexadecimal value. Default = 

08. 

del = /? Sets the input delete line character and 

requires a hexadecimal value. Default — 
18. 

bell = /i Sets the bell (alert) output character and 

requires a hexadecimal value. Default = 

07. 

eor = /? Sets the end-of- record (carriage return) 

input character. Requires a value in hexa- 
decimal. Default = 0D. 

eof=/? Sets the end-of-file input character. The 

numeric value the character is hexadecimal. 
Default = IB. 
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type = /? For external devices, type is used for ACJA 

initialization values (hexadecimal). The 
default = 00. Bits 5-7 set either MARK, 
SPACE, or no parity on all devices. Codes 
for these are: 

= no parity 
101 = MARK parity transmitted, no 

checking 
111 = SPACE parity transmitted, no 

checking 

011 = even parity only available 
with the ex- 

001 = odd parity ternal ACIA 
pak and 
Modpak 
devices. 

Bits 0-3 are reserved for future use. 

Bit 4 selects auto-answer modem support 
features. 

1 = on 

= off 

See Color Computer I/O Devices for 

further information. 

For TERM, the type byte has a different 

use: 

Bit specifies a machine with true 
lowercase capability. Set bit to turn 
on true lowercase. 

Bit 1 specifies output screen size. 
Clear bit 1 for 32 column output to 
the video screen. Set bit 1 for 80 col- 
umn output to the video screen 
through the 80 column card. 

reprint — h Sets the reprint line character. Use a hexa- 

decimal numeric value. 

dup = /? Sets character to duplicate last input line 

character and requires a hexadecimal value. 
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psc = h Sets pause character and requires a hexa- 

decimal value. 

aborts h Sets the terminate character (normally 

CONTROL C) and requires a hexadecimal 
value. 

quit^/7 Sets the quit character (normally CON- 

TROL H) and requires a hexadecimal value. 

baud-/? Sets baud, word length, and stop bits rate 

for software-controllable interface. The 
numeric codes for baud rate are: = 6E 
1 = 12C, 2 = 258, 3-4B0, 4 = 960, 
5=12C0, 6 = 2580, 7-4B00 value is in 
hexadecimal. 

Bits 0-3 determine the baud rate 
Bit 4 is reserved for future use 
Bits 5-6 determine the word length: 

00-8 bits 

01 =1 bits 
Bit 7 determines the number of stop 

bits: 

= 1 stop bit 

1 =2 stop bits. 

Notes: 

XMODE is similar to TMODE, but there are differences. 
TMODE operates only on open paths, so its effect is tempo- 
rary. XMODE updates the device descriptor; its change per- 
sists as long as the computer is running, even if you or the 
system repeatedly open and close the paths to the device. 

If you use XMODE to change parameters ) and the COB- 
BLER program to make a new system diskette or re-write 
system tracks on the current system diskette, the changed 
parameter is permanently on the new system diskette. 

XMODE requires that you specify a device name. If you do 
not specify parameters, the present values for each parameter 
display. You can use any number of parameters separating 
them by spaces or commas. 
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Other Utilities 



Examples: 

XMODE /TERM ~upc If null=4 bse=1F 
pause I ENTER \ 

XMODE /T1 pag=24 pause bsl -echo 
bsp = 8 [ ENTER I 



XMODE /P baud = 3 -If ENTER 



Several other OS -9 utilities are altered to adjust their screen 
size to either a 32 or 80 column display. This is done using 
the new SS.ScSiz GETSTAT call (see the GETSTAT call sec- 
tion of this addendum for full information.) 

The utilities altered in this manner are: 

CONFIG DIR DUMP LOGIN 

MDIR PROCS TMODE XMODE 
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Section 2 — System Changes 



Beep To create a short sound from your terminal speaker, 
send a CTRL G or character 7 to the terminal. You can cause 
a beep from BASIC with the command PRINT CHRS(7). To 
cause a beep from OS -9, type DISPLAY 07 [ENTER]. 

Error Codes System Error $DC (220 decimal) is defined 
as a HANG UP error and indicates that the RS232 data car- 
rier detect is lost. It replaces the ILLEGAL BLOCK SIZE 
error on page 164 of the OS-9 Technical Information manual. 

CCIO The Color Computer Input/Output module is now 
divided into three separate sections. The graphics portion of 
the module does not load on startup. To load the graphics 
portion, type LOAD GRFO at the OS-9 prompt. Because 
graphics draw routines are not pre-loaded, more memory is 
available for programs that do not require graphics capabili- 
ties. See Appendix B for more information on graphics. 

Video Output Separate subroutine modules, C032 and 
CO80 handle video output. C032 provides a standard 32 col- 
umn TV display and is included in the standard boot. CO80 
provides an 80 column video display when used in conjunc- 
tion with an optional 80 column card. 

Hard Disks A driver is available for one or two 15 or 35 
meg hard disk units. Use the CONFIG utility to prepare your 
system for hard disk capability. See Appendix E for more 
information on hard disks. 

Clock Interrupt A system change now permits clock inter- 
rupt accessibility to device drivers. See the VIRQ system call 
in Section 3. 

Drive Descriptors The descriptors for Disk Drives 2 and 3 
are removed from the OS-9 boot file. The descriptors are not 
resident in memory when the system is initialized. If you 
wish to use more than two disk drives, replace the descrip- 
tors in the boot file using OS9GEN, CONFIG, or 
COBBLER. 
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Graphics Display Buffer A ''Setstat" function now allows 
for allocation and deallocation of additional graphics buffers. 
See the SETSTAT system call in the next section. 

Graphics Driver Enhancements Several new graphics func- 
tions are added to the graphics module. See the information 
in the Appendix B Update. This is the updated version of the 
OS-9 Commands manual Appendix B, Display System 
Functions. 

Speech/Sound There is now a speech and sound driver 
added for the Speech/Sound Cartridge. Select the Speech/ 
Sound (ssc) driver through the CONFIG utility (See CONFIG 
in Section 1). 

Keyboard Driver Enhancements The keyboard driver now 
has an auto key-repeat and the capability of generating new 
codes and status values. The following new features are 
added through the GETSTAT system call: 

• GETSTAT now returns the current key press status for the 
following keys: 

I SHIFT I 



[CTRL] ([ CLEAR j) 

m 

CD 
Q 
H 

the spacebar 
See GETSTAT in System Calls for more information. 



serves as an ALT key to set the high order bits on 
characters typed from the keyboard. For instance, pressing 
[~a] generates a code of 65 (producing a character A), 
pressing [ ALT ][~A] generates a code of 193 (producing a 
graphics character) 

• The auto key-repeat feature causes a key to repeat when 
you press it for longer than one second. 
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SCF Descriptor Tables 



Add the following information to the path descriptor table 
SCFMAN Option Section Definition (PD.OPT Section), 
beginning on Page 55 of the OS -9 Technical Information 
manual. PD.XON replaces the previous PD.STN entry. 



Name 



Relative Size 
Address (Bytes) Use 



PD.XON 
PD.XOFF 



$38 
$39 



ACIA XON char 
ACIA XOFF char 



PD.XON contains either the character to enable trans- 

mission of characters or a null to disable 
XON. 

PD.XOFF contains either the character to disable 

transmission of characters or a null to dis- 
able XOFF. 

PD.PAR specifies parity information for external 

serial devices. See the explanation of the 
TMODF type byte in this addendum for 
more information. 

PD.BAU specifies baud rate, word length, and stop 

bit information for serial devices. See the 
explanation of the TMODE baud byte in 
this addendum for more information. 

SCF-Device Memory Area Definitions 

Add the following information to the SCF-Device Memory 
Area Definitions table, beginning on page 59 of the OS-9 
Technical Information manual. (V.XON replaces the previous 
entry, V.SCF in the table.) See the OS9DFFS directory on 
your system diskette for additional information. 
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Relative 


Size 




Name 


Address 


(Bytes) 


Use 


V.XON 


$0F 


1 


XON character 


V.XOFF 


$10 


1 


XOFF character 


V.KANJI 


$11 


1 


Reserved 


V.KBUF 


$12 


2 


Reserved 


V.MODAPR 


$14 


2 


Reserved 


V.PDLHD 


$16 


2 


Header of path 
descriptor list 


V.RSV 


$18 


5 


Reserved 


V.SCF equ 


SID 




Hnd of SCF memory 
requirements 



Add the following information to the SCF -Type Device 
Descriptor Modules table on Page 51 of the OS -9 Technical 
Information manual: 





Relative 


Size 




Name 


Address 


(Bytes) 


Use 


IT. XON 


$2A 




1 


X-ON character 


IT. XOFF 


$2B 




I 


X-OFF character 


IT. COL 


$2C 




1 


Number of screen 
columns 


IT. ROW 


$2D 




1 


Number of screen 
rows 


Note: IT. XON 


replaces 


the 


previous 


; IT.STN entry in the 


device descriptor. 
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Section 3 — System Calls 



GETSTAT 

OS-9 I$GETSTT 



103F 8D 



Function: 

Gets the status of a device. This call is a "wild card" call 
used to handle individual device parameters that: 

• are not uniform on all devices 

• are highly hardware dependent 

• need to be user-changeable 

Following are the currently defined function codes for 
GETSTAT; 

Mnemonic Code Function 



SS.Opt 

SS. Ready 

SS.Size 

SS.Pos 

SS.Eof 

SS.DevNm 

SS.DStat 

SSJoy 

SS.AlfaS 

SS.Cursr 

SS.ScSiz 

SS.KySns 



$00 

$01 
$02 
$05 
$06 
$0E 
$12 
$13 
$1C 
$25 
$26 
$27 



SS.ComSt $28 



Reads the 32 byte options section of 
the path descriptor 
Tests for data ready (RBF, ACIA) 
Returns the current file size (RBF) 
Gets the current file position (RBF) 
Test for the end of file (RBF, ACIA) 
Returns the device name (IOMAN) 
Returns graphics display information 
Returns joystick information 
Returns alpha screen information 
Returns cursor information 
Returns screen size information 
Returns the key down information 
packet 

Returns parity, stop bit, word length, 
baud rate information for SCF devices 



Following are the parameter passing conventions for the 
GETSTATS function codes. 
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SS.Opt (Code $00) Reads the option section of the path 
descriptor and copies it into the 32-byte area pointed to by 
Register X. Use this code to determine the current settings 
for editing functions such as echo and auto line feed. For a 
complete description of the status packet, see the section on 
path descriptors. 

Entry Conditions: 

A = path number 

B - $00 

X ~ address of place to put a 32-byte status packet 

Exit Conditions: 
Status packet 

Error: 

CC - C bit set 

B = error code 

SS. Ready (Code $01) Tests for data available on SCF-sup- 
ported devices. 

Entry Conditions: 

A = path number 
B - $01 

Exit Conditions: 
If ready; 

CC = C bit clear 

B = number of bytes available, or if the byte count 
is not supported by the driver. 

If not ready: 

CC = C bit set 

B = $F6 (E$NotRDY) 

Error: 

CC - C bit set 
B = error code 
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SS.Size (Code $02) Gets the current file size (RBF-sup- 

ported devices only). 

Entry Conditions: 

A - path number 
B - $02 

Exit Conditions: 

X = ms 16 bits of the current file size 
U = Is 16 bits of current file size 

Error: 

CC = C bit set 
B = error code 

SS.Pos (Code $05): Gets the current file positions (RBF- 

supported devices only). 

Entry Conditions: 

A = path number 
B = S05 

Exit Conditions: 

X = ms 16 bits of the current file position 
U = Is 16 bits of the current file position 

Error: 

CC - C bit set 

B = error code 

SS.EOF (Code $06): Tests for end of file. 

Entry Conditions: 

A = path number 
B = $06 

Exit Conditions: 



Not EOF 


C bit set 


Error 


C bit clear 


C bit set 


C bit set 


zero 


$D3 (E$EOF) 


Error codes 
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Error: 

CC = C bit set 

B = appropriate error code 

SS.DevNm (Function Code $0E): Returns the device 
name. 

Entry Conditions: 

A = path number 

B - $0E 

X = address of 32-byte area for device name 

Exit Conditions: 

Device name in 32-byte storage area 

SS.DStat (Code $12): Returns the display status. 

Entry Conditions: 

A = path number 
B - $12 

Exit Conditions: 

X = address of the graphics display memory 

Y = graphics cursor address; x = msb, y = Isb 
A = color code of the pixel at the cursor address 

SS.Joy (Code $13): Returns the joystick values. 

Entry Conditions: 

A = path number 

B = $13 

X = (right joystick) or 1 (left joystick) 

Exit Conditions: 

X = selected joystick x value (0-63) 

Y = selected joystick y value (0-63) 

A = $FF (if fire button is on) or $00 (if fire button 
is off) 

SS. AlfaS (Code $1C): Returns information about alpha 
screen memory. 

Entry Conditions: 

A = path number 
B = $1C 
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Exit Conditions: 

A = caps lock status 

$00 = lowercase 

$FF = uppercase 
X = address of buffer in memory 
Y - address of cursor in memory 

SS.Cursr (Code $25): Returns cursor information from 
alpha screen. 

Entry Conditions; 

A = pathnumber 

B = $25 

Exit Conditions: 

A = character under cursor 

X = x position of cursor (column) 

Y = y position of cursor (row) 

SS.ScSiz (Code $26): Returns size of screen (default from 
descriptor). 

Entry Conditions 

A = pathnumber 
B = $26 

Exit Conditions: 

X — number of columns on screen 

Y = number of rows on screen 

Note: These are the bytes IT. COL and 1T.ROW follow- 
ing the IT.XOFF byte in the device descriptor. See 
SCF-Type Device Descriptor Modules in the OS -9 Tech- 
nival Information manual for full information. 

SS.KySns (Code $27): Returns key down information 
packet. 

Entry Conditions: 

A = path number 

B = $27 
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Exit Conditions: 



= byte with bits set to indicate which key was 
down at the last keyboard scan, 

= bit not set and key not down 

1 = bit set and key down 



Bit 


Key 





= Shift Key 


1 


= Control/Clear Key 


2 


= AW (a key 


3 


= Up arrow key 


4 


= Down arrow key 


5 


= Left arrow kev 


6 


= Right arrow key 


7 


= Space key 



The following information can be included as equates 
for the different bit positions: 

SHIFTBIT equ %00000001 
CNTRLB1T equ %00000010 
ALTERBIT equ %00000100 
UPBIT equ %00001000 

DOWNBIT equ %000 10000 
LEFTBIT equ %00 100000 
RIGHTBIT equ %0 1000000 
SPACEBIT equ % 10000000 

SS.ComSt (Code $28): Return information on parity, stop 
bits, word length, and baud rate for SCF devices. 

Entry Conditions: 

A = path number 
B - $28 

Exit Conditions: 

Y = msb parity byte of path descriptor (parity) 

lsb baud rate of path descriptor (baud, word 
length, stop bits) 
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High order byte of Y: 

Bits 0-4 - Reserved 
Bits 5-7 - Parity code 

000 = no parity 

001 = odd parity transmitted and 

received 
011 - even parity transmitted and 

received 
101 = mark parity transmitted, no 

receiver parity checked 
111 = space parity transmitted, no 

receiver parity checked 

Note: Reserved bits are used by some Color 
Computer drivers. 

Low order byte of Y: 

Bits 0-3 - Baud rate code 





0-110 




1 - 300 




2 - 600 




3 - 1200 




4 = 2400 




5 = 4800 




6 - 9600 




7 = 19200 


Bit 4 - 


Reserved 


Bits 5-6 


- Word length 




00-8 bits 




01-7 bits 


Bit 7 - 


Stop Bits 




- 1 stop bit 




1 = 2 stop bits 



SCF uses this call to determine what the current values for 
PD.PAR and PD.BAU should be. You can make this call, but 
doing so does not update the path descriptor. Use SS.Opt to 
maintain the path descriptor in a valid state. 
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SETSTAT 

EOS-9 I$SETSTT 



103F 8E 



Function: 

Sets the status of a device. This call is a lt wild card 1 * call 
used to handle individual device parameters that: 

• are not uniform on all devices 

• are highly hardware dependent 

• need to be user-changeable 

Following are the presently defined function codes for 
GETSTAT: 



Mnemonic 



Code 



Function 



SS.Opt 



$00 



SS.Size 


$02 


SS. Reset 


$03 


SS.WTrk 


$04 


SS.Feed 


$09 


SS.FRZ 


$0A 


SS.SPT 


$0B 


SS.SQD 


$0C 


SS.DCMD 


$0D 


SS.KySns 


$27 


SS.ComSt 


$28 


SS.AAGBf 


$80 


SS.SLGBf 


$81 



Writes the 32 byte 
options section of the 
path descriptor 
Sets the file size (RBF) 
Restores head to track 
zero 

Writes (format) track 
Issues Form Feed (SCF) 
Freezes DD. information 
Sets sectors per track 
Disk drive sequence 
down 

Directs command to disk 
collector 

Enables/Disables key- 
board sense ability 
Sets baud, parity, stop 
bit, word length informa- 
tion for SCF devices. 
Allocates additional 
graphics buffers 
Select graphics buffer 
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SS.Opt (Code $00): Writes the option section of the path 
descriptor from the 32-byte status packet pointed to by the X 
register. It is typically used to set the device operating 
parameters, such as echo and auto line feed. 

Entry Conditions: 

A = path number 

B - $00 

X - address of a 32-byte status packet 

Exit Conditions: none 

SS.Size (Code $02): Set file size for RBF-type devices. 

Entry Conditions: 

A = path number 

B = $02 

X = ms 16 bits of desired file size 

U = Is 16 bits of desired file size 

Exit Conditions: none 

SS. Reset (Code $03): Restores disk drive head to track 
zero. 

Entry Conditions: 

A = path number 
B - $03 

Exit Conditions: none 

SS.Wtrk (Code $04): Formats a floppy diskette track. The 
entire diskette is formatted when the track number equals 
zero. 

Entry Conditions: 

A = path number 

B - $04 

X - address of track buffer 

U = track number 
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Y = side/density 

Bit B0 = side (0 = side zero, 1 = side 

one) 

Bit Bl = density (0 = single, 1 = double) 

(The high order byte contains the number of 

sides) 

Exit Conditions: none 

SS.FRZ (Code $0A): Inhibits the reading of the identifica- 
tion sector (LSN 0) to memory so non-standard disks can be 
read. 

Entry Conditions; 

A = path number 
B = $0A 

Exit Conditions: none 

SS.SPT (Code $0B): Sets a different number of sectors per 
track so non-standard disks can be read. 

Entry Conditions: 

A = path number 

B - S0B 

X = new sectors per track 

Exit Conditions: none 

SS.SQD (Code $0C): Sequence down — initiates power- 
down sequence for Winchester or other hard disks which have 
sequence -down requirements prior to the removal of power. 

Entry Conditions: 

A = path number 
B - $0C 

Exit Conditions: none 

SS.KySns (Code $27): Sets or resets special key sense 
function according to the contents of X. 

Entry Conditions: 

A = path number 
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B = $27 

X = Keysns switch value 

= disable key sense and return to normal key 
operation 

1 = enable key sense mode 

Exit Conditions: none 

Error: 

CC = C set on error 

B = Error code if one exists 

With the keyboard in the key sense operation mode, the keys 
in the following list do not send characters to SCF devices or 
to the screen when pressed. The only method of determining 
a keypress is through the GETSTAT call. Take care to re- ena- 
ble the standard mode before reading commands from the ter- 
minal. The KeySns GETSTAT call returns the proper bits set 
even if the keys are all generating output. 



Key Sense Code: 


Bit 


Key 









[SHIFT] 


1 


[ CTRL ][ CLEAR J 


2 
3 
4 
5 
6 
7 


( ALT |/[@J 

Q 

CD 

Q 
Q 

The spacebar 


The following is suggested equates for the bit f 


SHIFTBIT equ 


%00000001 


CNTRLBIT equ 


%00000010 


ALTERBIT equ 


7.00000100 


UPBIT equ 


%00001000 


DOWNBIT equ 


%000 10000 


LEFTBIT equ 


%00 100000 


RIGHTBIT equ 


%0 1000000 


SPACEBIT equ 


% 10000000 
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SS.ComSt (Code $28): Sets parity, baud, word length, and 
stop bit information for SCF-type devices. 

Entry Conditions: 

A - path number 
B - $28 

Exit Conditions: 

Y = msb parity bite 

lsb baud byte (baud, word length and stop bits) 

SSCF devices currently use this Setstat to inform a driver 
that the parity or baud bytes are changed in the path descrip- 
tor. If you make this Setstat call, the path descriptor is not 
updated until you make the next SS.Opt Getstat call. Then, 
the path descriptor is updated with the new information. 

SS.HngUp (Code $2B): Flushes buffers and shuts down 
modem port on phone hang up. 

Entry Conditions: 

A = path number 
B = S2B 

Exit Conditions: none 

You can use this call with true ACIA drivers (T2, T3, Ml, 

M2). 

SS.AAGBf (Code $80): Allocates additional graphics 
buffer — sets additional 6K graphic buffers. Select the first 
buffer with the standard DISPLAY graphics command (writ- 
ing control code 15 to the standard terminal driver). Request 
additional buffers (as many as three) by using this Setstat. 
Buffers are numbered 0-2 where is the buffer allocated by 
the DISPLAY graphics command and 1 and 2 are buffers 
allocated using the SS.AAGBf Setstat. The additional buffers 
affected by this routine remain allocated until the end graph- 
ics command is received. 

Entry Conditions: 

A = path number 
B - $80 
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Exit Conditions: 

X = address of buffer 

Y = buffer number (0, 1, 2) 

Error; 

CC - C bit set 
B = error code 

SS,SLGBf (Code $81): Selects graphics buffer as the cur- 
rent draw and display buffer or the current display buffer. 
You can select buffers as foreground buffers without display- 
ing them. The SS.Dstat call returns the address of the current 
foreground buffer and not necessarily the displayed buffer. 

Entry Conditions: 

A = path number 
B - $81 
X = mode 

= select buffer as current use buffer 
non = select buffer as current use buffer and 
cause the buffer to be displayed 
beginning at the next clock interrupt. 

Y = buffer number (0, 1, 2) 

You can select an additionally allocated buffer and draw in it 
before you display it. Use SS.SLGBF to cause the foreground 
screen to display at the next clock interrupt. 

Exit Conditions: 

X = mode (unchanged) 

Y = buffer number (0, 1, 2) (unchanged) 

Error: 

CC = C bit set 
B = error code 
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VIRQ 

EOS-9 F$VIRQ 103F 27 



Function 

Sets the number of clock ticks at which a device can be 
interrupted. VIRQ is useful with devices in the Multi-Pak 
expansion slots that can generate physical interrupts on the 
processor but which cannot be recognized by the processor 
because of the lack of an IRQ line from the Multi-Pak. It is 
also useful for devices without physical interrupts. VIRQ can 
be used to simulate such a physical interrupt. 

Entry Conditions 

Y = address of 5-byte packet 

X ~ to delete entry, 1 to install entry 

D = initial count value 

Exit Conditions: none 

The VIRQ polling table is handled by the CLOCK module 
and is dependent on the clock being initialized. SYSGO 
forces the clock to start in OS-9 versions 02.00.00 and later. 

The virtual interrupt is set so that a device can interrupt at a 
given number of clock ticks. The interrupt can occur once, 
or can be repeated as long as the device is used. The VIRQ 
call requires a five byte packet specified for use in its table. 
This packet contains: 

• Bytes for an actual counter 

• A reset value for the counter 

• A status byte that indicates whether a Virtual Inter- 
rupt has occurred and whether the VIRQ is to be 
reinstalled in the table after being issued 

• A tick count that is used as an initial count for the 
interrupt 
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The five-byte packet is defined as follows: 

Name Offset Function 

Vi.Cnt $00 Actual counter 

Vi.Rst $02 Reset value for counter 

Vi.Stat $04 Status byte 

Two of the bits in the status byte are used, these are: 
Bit - Set if VIRQ occurs 
Bit 7 - Set if count is to be reset 

When making a FSVIRQ call, initialize the packet with a 
reset value, if required. Also, you must either set or clear bit 
7 of the status byte to signify a reset of the counter or a one 
time VIRQ call. The reset value does not need to be the 
same as the initial counter value. When the call is processed, 
the address of the packet is installed on the VIRQ table, 
where it can be accessed by the clock module. 

At each clock tick the table is parsed (scanned) and the tim- 
ers are decreased by one. When the count becomes zero, the 
following actions occur: 

• Bit is set in the status byte, specifying a Virtual 
IRQ 

• Bit 7 of the status byte is checked to see whether the 
count is to be reset 

• If bit 7 is set, the count is reset using the reset 
value, otherwise the entry is deleted from the table. 

When a Virtual IRQ results from a counter dropping to zero, 
the standard polling routine is executed, and the interrupt is 
serviced. Thus, you must install entries on both the VIRQ 
and IRQ polling tables to use the VIRQ. 

Install the device on the IRQ polling table using the F$IRQ 
system call before you place it on the VIRQ table, unless the 
device has an actual physical interrupt that can be found on a 
hardware register. If the device has such an interrupt, use 
that as the polling address for the F$IRQ system call, along 
with the proper flip and mask bytes for the device. If the 
device has no interrupts, and is totally VIRQ driven, use the 
status byte from the VIRQ packet as the status byte, and use 
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a mask byte of %00000001 defined as VJ.IFlag in the defs 
file. Use a flip byte of 0. 

F$VIRQ is a privileged system call. 
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Appendix B Update 



Display System Functions 



Color Computer OS -9 lets you use the video display in 
alphanumeric, semigraphic, and graphic modes. There are 
many built-in functions to control the display. You activate 
these functions using ASCII control characters. They are 
available to any software written in a language using standard 
output statements (such as PRINT in BASIC). Color Com- 
puter BASIC09 has a Graphics Interface Module that can 
automatically generate most of these codes using BAS1C09 
RUN statements. 

The display system has two display modes: Alphanumeric 
(Alpha) and Graphics. The Alphanumeric mode also includes 
semigraphic box-graphics. The Color Computer's display sys- 
tem uses a separate memory area for each display mode so 
operations on the Alpha display do not affect the Graphics 
display, and vice- versa. Either display can be selected under 
software control. (See Getting Started With Extended Color 
BASIC for more detailed information.) 

Eight-bit characters sent to the display system are interpreted 
according to their numerical value, as shown in this chart: 

Character 
Range (Hex) Mode/Used For 

00 - 0E Alpha Mode — Cursor and screen control. 

0F - ID Graphics Mode — Drawing and screen control. 

IE - IF Escape loading for 80 column display. 

20 - 5F Alpha Mode — Upper case characters. 

60 - 7F Alpha Mode — Lower case characters. 

80 - FF Alpha Mode — Semigraphic patterns. 

The Color Computer OS -9 alphanumeric functions are han- 
dled by the OS-9 device driver module called CCIO, and one 
of several output routines. The basic graphics functions are 
all handled by CCIO using the GRFO subroutine procedure 

for processing. 
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Alpha Mode Display 



This is the standard operational mode. Use it to display 
alphanumeric characters and semigraphie box graphics, and 
to simulate the operation of a typical computer terminal with 
functions for scrolling, cursor positioning, clear screen, line 
delete, and so on. 

This mode assumes that each 8-bit character is an ASCII 
character. This character displays if its high order bit (sign 
bit) is cleared. If the high order bit of the character is set, 
the character is assumed to be a Semigraphie 6 graphics box. 
See Getting Started With Extended Color BASIC for an expla- 
nation of seriographies functions. 

The standard Alpha mode display is handled by the I/O sub- 
routine module C032. CCIO calls this module (included in 
the standard boot file) to process all text and semigraphie 
output. 

If you have the optional 80-Column Cartridge and a monitor 
capable of 80 columns, you can use the CO80 subroutine 
module to give an 80 column text display. If the CO80 sub- 
routine module is not found in memory it loads automati- 
cally. This subroutine is not included in the standard boot 
file, but is in the CMDS directory of the CONFIG/BOOT 
diskette. You can included the subroutine in a boot file using 
the CONFIG utility. 

Both text display subroutine modules can be present in mem- 
ory to allow alternate access to both the 32 column television 
output and the 80 column monitor output. Switch to 80 col- 
umn mode to use the 80 column output. Switch off the 80 
column mode to again use 32 column output. The mode 
switch is handled by the par byte of the path descriptor 
(described in the section of this addendum dealing with 
TMODE). To turn on 80 column text use TMODE type -02. 
To turn it off, use TMODE type = 00. The following Alpha 
mode command codes are exactly the same for the 80 col- 
umn display and for the 32 column display. 
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Alpha Mode Command Codes 



Hex Decimal 
Control Control 
Code Code Name/Function 

$01 01 HOME — returns the cursor to upper 

left corner of screen. 

$02 02 CURSOR XY— moves the cursor to 

character X or line Y. Use the binary 
values minus 32 of the two characters 
following the control character as the X 
and Y coordinates. For example, to 
position the cursor at character 5 of line 
10, use X = 37 and Y = 42. 

$03 03 ERASE LINE— erases all characters 

on the cursor line. 

$04 04 CLEAR TO END OF LINE— erases 

all characters from the current cursor 
position to the end of the line. 

$05 05 CURSOR ON-OFF— allows alteration 

of the cursor based on the value of the 
next character. Codes are as follow: 



Hex 


Dec 


Char Function 




$20 


32 


span 


t Cursor OFF 




$21 


33 


] 


Cursor ON . 
(blue) 


. Default color 


$22 


34 


" 


Cursor ON . 


. Black 


$23 


35 


# 


Cursor ON . 


. Green 


$24 


36 


$ 


Cursor ON . 


. Yellow 


$25 


37 


% 


Cursor ON . 


. Blue 


$26 


38 


& 


Cursor ON . 


. Red 


$27 


39 


' 


Cursor ON . 


. Buff 


$28 


40 


( 


Cursor ON . 


. Cyan 


$29 


41 


) 


Cursor ON . 


. Magenta 


$2A 


42 


* 


Cursor ON . 


. Orange 
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Hex 


Decimal 


Control 


Control 


Code 


Code 


$06 


06 


$08 


08 


$09 


09 


$0A 


10 



Name/Function 

CURSOR RIGHT—moves the cursor 
to the right one character position. 

CURSOR LEFT — moves the cursor to 
the left one character position. 

CURSOR UP — moves the cursor up 
one line. 

CURSOR DOWN (linefeed)— moves 

the cursor down one line. 

$0C 12 CLEAR SCREEN— erases the entire 

screen and home cursor. 

$0D 13 RETURN— returns the cursor to left- 

most character of line. 

$0E 14 DISPLAY ALPHA— switches the 

screen from graphic mode to alpha- 
numeric mode. 

Command Codes for 80-Column Card 

$1F $20 31 32 TURN OFF ATTRIBUTES— turns off 

reverse video for 80-column display. 

S1F $21 31 33 TURN ON ATTRIBUTES— turns on 

reverse video for 80-column display. 



Graphics Mode Display 



Use the graphics mode to display high-resolution two- or 
four-color graphics. This mode includes commands to set 
color, plot and erase individual points, draw and erase lines, 
position the graphics cursor, and draw circles. 
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You must execute the display graphics command before using 
any other graphics mode command. This command causes 
the graphics screen to display and sets a current display for- 
mat and color. 

The first time you enter the display graphics command, OS-9 
allocates a 6144 byte display memory. There must be at least 
that much continuous free memory available. (You can use 
MFREE to check free memory.) This memory is retained 
until you give the end graphics command, even if the pro- 
gram that initiated Graphics mode finishes. It's important to 
use the end graphics command to give up the display mem- 
ory when you no longer need Graphics mode. 

Graphics mode supports two basic formats. The two-color 
format has 256 horizontal by 192 vertical points (G6R 
mode). The four-color format has 128-horizontal by 192 ver- 
tical points (G6C mode). Two color sets are available in 
either mode. Regardless of the resolution of the selected for- 
mat, all graphics mode commands use a 256 by 192 point 
coordinate system. The X and Y coordinates are always posi- 
tive numbers. Point 0,0 is the lower left corner of screen. 

Many commands use an invisible Graphics Cursor to reduce 
the output required to generate graphics. You can explicitly 
set this cursor to any point by using the set graphics cursor 
command. You can also use any other commands that include 
X, Y coordinates (such as set point) to move the graphics 
cursor to the specified position. 

Any graphics function that draws on the graphics screen 
requires the GRFO subroutine loaded into memory. This 
module is contained in the CMDS directory of the standard 
OS-9 system diskette. Load it with the command LOAD 
GRFO. You can also install the GRFO module as part of the 
boot operation by creating a new system diskette using the 
CONFIG utility described in this addendum. 



51 



Graphics Mode Selection Codes 



Code Format 

00 256 x 192 two-color graphics 

01 128 x 192 four-color graphics 

COLOR SET AND CURRENT FOREGROUND 
COLOR SELECTION CODES 







T\vo-Color 


Four-Color 






Format 


Format 






Back- 


Fore- 


Back- 


Fore- 




Char 


ground 


ground 


ground 


ground 




00 


Black 


Black 


Green 


Green 


Color 


01 


Black 


Green 


Green 


Yellow 


Set 1 


02 






Green 


Blue 






03 




Green 


Red 




04 


Black 


Black 


Buff 


Buff 


Color 


05 


Black 


Buff 


Buff 


Cyan 


Set 1 


06 






Buff 


Magenta 




07 






Buff 


Orange 




08 






Black 


Black 


Color 


09 






Black 


Dark Green 


Set 1 


10 






Black 


Med. Green 




11 






Black 


Light Green 




12 






Black 


Black 


Color 


13 






Black 


Green 


Set 1 


14 






Black 


Red 




15 






Black 


Buff 
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Graphics Mode Control Commands 



Hex Decimal 
Control Control 
Code Code Name/Function 

$0F 15 DISPLAY GRAPHICS switches 

the screen to the graphics mode. Use 
this command before any other graph- 
ics 1 commands. The first time you 
use it, a 6K byte display buffer is 
assigned. If 6K of contiguous mem- 
ory isn't available, an error is 
returned. Follow this command with 
two characters specifying the graphics 
mode and current color/color set, 
respectively. This is part of CCIO 
and does not require GRFO. 

$10 16 PRESET SCREEN— presets the 

entire screen to the color code passed 
by the next character. This function is 
processed by CCIO and does not 
require GRFO. 

$11 17 SET COLOR— selects foreground 

color (and color set) passed by the 
next character, but does not change 
the graphics mode. This function is 
processed by CCIO and does not 
require GRFO. 

$12 18 END GRAPHICS disables the 

graphics mode and returns the 6K 
byte graphics memory area to OS-9 
for other use. It also switches to 
alpha mode. This function is pro- 
cessed by CCIO and does not require 
GRFO. 
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Hex Decimal 
Control Control 
Code Code Name/Function 

$13 19 ERASE GRAPHICS— erases all 

points to the background color and 
locates the graphics cursor at the 
desired position. This function is pro- 
cessed by CCIO and does not require 
GRFO. 

$14 20 HOME GRAPHICS CURSOR— 

moves the graphics cursor to coordi- 
nates 0,0 (lower left-hand corner). 
This function is processed by CCIO 
and does not require GRFO. 

$15 21 SET GRAPHICS CURSOR— moves 

the graphics cursor to the given X, Y 
coordinates. The binary value of the 
two characters that immediately fol- 
low are used as the X and Y values, 
respectively. 

$16 22 DRAW LINE— draws a line of the 

current foreground color from the cur- 
rent graphics cursor position to the 
given X,Y coordinates. The binary 
value of the two characters that 
immediately follow are used as the X 
and Y values, respectively. The 
graphics cursor moves to the end of 
the line. 

$17 23 ERASE LINE — operates the same as 

the draw line function, except that the 
line is drawn in the current back- 
ground color, thus erasing the line. 
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Hex Decimal 
Control Control 
Code Code Name/Function 

$18 24 SET POINT— sets the pixel at point 

X,Y to the current foreground color. 
The binary values of the two charac- 
ters that immediately follow are used 
as the X and Y values, respectively. 
The graphics cursor moves to the 
point set. 

$19 25 ERASE POINT— operates the same 

as the draw point function, except the 
point is drawn in the current back- 
ground color, thus erasing the point. 

$1A 26 DRAW CIRCLE— draws a circle of 

the current foreground color around 
the current graphics cursor (as the 
center point) using the radius obtained 
from the binary value of the next 
character. 

$1C 28 ERASE CIRCLE— operates the 

same as the draw circle function, 
except that the circle is drawn in the 
current background color, thus erasing 
the circle. 

$1D 29 FLOOD ¥UA.— paints the current 

foreground color starting at the graph- 
ics cursor position and extending over 
adjacent pixels having the same color 
as the pixel under the graphics cursor. 

Note: When fill is called for the first 
time it requests allocation for a 512 
byte stack for the fill routine. This 
memory is not returned until you ter- 
minate graphics with the end graphics 
command. 

Note: Hexadecimal codes are for compatibility with the 
OS -9 Display command. 
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Get Status Commands 



The Color Computer I/O driver includes OS-9 get status 
commands that return information about the keyboard, dis- 
play, and joysticks. All are accessed using the assembly lan- 
guage system calls listed. You can access the first two calls 
using the BASIC09 Graphics Interface Module. 



Get Display Status: 



Calling Format: Ida #1 

ldb #SS.DStat 



Passed: 
Returns: 



os9 I$GSTT 
nothing 



(path number) 
(Getstat code $12) 
(call OS-9) 



X = address of graphics display 

memory 
Y = graphics cursor address ^ 
A = color code of pixel at cursor 

address 



Note: This command is available through the 
BASIC09 Graphics Interface Module. 



Get Joystick Values: 



Calling Format: Ida #1 

ldb SSS.Joy 
os9 I$GSTT 



(path number) 
(Getstat code $13) 
(call OS-9) 



Passed: X = for right joystick; 1 for left 

joystick 

Returns: X = selected joystick x value (0-63) 

Y = selected joystick y value (0-63) 
A = SFF if fire button on; $00 if off 

Note: This command is available through the 
BASIC09 Graphics Interface Module. 
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Get Alpha Display Status: 



Calling Format: 


ldb #1 (path number) 




ldb #SS.AlfaS (Getstat code $1C) 




os9 I$GSTT (call OS-9) 


Passed: 


nothing 


Returns: 


A = caps lock status 




$00 = lowercase 




$FF = uppercase 




X = address of buffer in memory 




Y = address of cursor in memory 



Get Alpha Cursor Status: 



Calling 


Format: 


Ida #1 


(path number) 






Ida #SS.Cursr 


(Getstat code $25) 






os9 I$GSTT 


(call OS-9) 


Passed: 




nothing 




Returns: 




A = character under cursor 






X = x position 


of cursor (column) 






Y = y position 


of cursor (row) 



Get Screen Size: 



Calling 


Format: 


Ida #1 


(path number) 






ldb #SS.ScSiz 


(Getstat code $26) 






os9 ISGSTT 


(call OS-9) 


Passed: 




nothing 




Returns: 




X = number of columns on screen 






Y = number of 


rows on screen 
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Get Key Sense Information: 



Calling Format: Ida #1 (path number) 

ldb #SS.KySns (Getstat code $27) 
os9 I$GSTT (call OS-9) 

Passed: nothing 

Returns: A = status byte with bits set indicat- 

ing a key was depressed on last 
keyboard scan. 

- bit not set, key NOT 

down 

1 = bit set, key down 

Bit Key 

= shift key 

1 = control/Clear key 

2 = -d\t/(a key 

3 = up arrow key 

4 = down arrow key 

5 = left arrow key 

6 = right arrow key 

7 - spacebar 

Note: To enable this command, you must enable 
the Key Sense mode using the Enable/Disable 
Key Sense set status command. 



Set Status Commands 



The Color Computer I/O driver includes OS-9 set status com- 
mands that lets you alter the keyboard or display status. 

Enable/Disable Key Sense Ability: 

Calling Format: Ida #1 (path number) 

ldb #SS. KySns (Setstat code $27) 
ldx #KySnsVal (0 to disable, 1 to 

enable) 
os9 I$SETSTT (call OS-9) 
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Passed: x = to disable key sense mode 

I to enable key sense mode 
Returns: nothing 



Allocate Additional Graphics Buffers 



Calling Format: 



Passed: 
Returns: 



Ida # 1 (path number) 

ldb #SS.AAGBf (SetStat code $80) 
os9 1SSETSTT (call OS-9) 



nothing 

X — address of butler 

Y = buffer number (0, 1, 



2) 



Select Graphics Buffer 



Calling Format: 



Passed: 



Returns: 



Ida #1 

ldb #SS.SLGBf 
ldx #Mode 
ldy #BUFNUM 

os9 ISSETSTT 



(path number) 
(SetStat code $81) 
(get mode) 
(get buffer 
number) 
(call OS-9) 



X = mode: 

~ select buffer as current 

use buffer 

> = select current buffer and 

cause it to be displayed 

beginning at next clock 

interrupt. 

Y = buffer number (0, 1 or 2) 

X - mode, unchanged 

Y = buffer number, unchanged 
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Display Control Codes Condensed Summary 



1st 


Byte 








Dec 


Hex 


2nd Byte 


3rd Byte 


Function 


00 


00 






Null 


01 


01 






Home alpha cursor 


02 


02 


Column 4- 32 


Row + 32 


Position alpha cursor 


03 


03 






Erase line 


04 


04 






Erase to End of line 


05 


05 


Cursor Code 




Alter Cursor 


06 


06 






Cursor right 


08 


08 






Cursor left 


09 


09 






Cursor up 


10 


0A 






Cursor down 


11 


0B 






Erase to End of Screen 


12 


0C 






Clear screen 


13 


0D 






Carriage return 


14 


0E 






Select alpha mode 


15 


0F 


Mode 


Color Code 


Select graphics mode 


16 


10 


Color Code 




Preset screen 


17 


11 


Color Code 




Select color 


18 


12 






Quit graphics mode 


19 


13 






Erase screen 


20 


14 






Home graphics cursor 


21 


15 


X Coord 


Y Coord 


Move graphics cursor 


22 


16 


X Coord 


Y Coord 


Draw line to X/Y 


23 


17 


X Coord 


Y Coord 


Erase line to X/Y 


24 


18 


X Coord 


Y Coord 


Set point at X/Y 


25 


19 


X Coord 


Y Coord 


Clear point at X/Y 


26 


1A 


Radius 




Draw circle 


28 


1C 


Radius 




Erase circle 


29 


ID 






Flood Fill 
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Appendix D Update 



Keyboard Control Functions 



Key Definitions for Special Functions and Characters 

KEY CONTROL FUNCTION 

COMBINATION OR CHARACTER 



r@~lorfALT] 



CTRL or CLEAR 



BREAK or CTRL E 



[cTrl]Q 



[ctrTJQ 



^TRnn 



Alternate key — sets the high order 
bit on a character. Press [ @ \CHAR 



or |ALTl C7M/g. If your keyboard 
does not have \~MJ~] use 



Used as a control key (_ 
Some Color Computers 

[CLEAR]. 



CTRL 



use 



Stops the program currently 
executing. 

Generates an underline ( ) char- 
acter. The underline character dis- 
plays as a left arrow (PH). 

Generates a left brace ({) character. 
The left brace character displays as 
a left bracket ([) in reverse video. 

Generates a right brace (}) charac- 
ter. The right brace character dis- 
plays as a right bracket (J) in 
reverse video. 



| CTRL J L^J 


Generates a tilde (~) character. The 
tilde displays as a hyphen (-) in 
reverse video. 


( CTRL ] [ / ] 


Generates a reverse slash (\) 
character. 


[ CTRL ]| BREAK ] 


Generates an end-of-file (EOF). 



This sequence is the same as [ ESC] 
on a standard terminal. 
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( SHIFT lf@1 

Q or [CTRDQD 

1 SHIFT | P] C) r ( CTRL [fx] 



1 SHIFT BREAK or 



^TRT] P1 



CTRL 



CTRL 1 



CTRL 7 



CTRL 8 



CTRL 9 



fCTRLKTI 
[ CTRL |fW] 

[CLEAR IP 



Generates the fa character. 

Generates a backspace. 

Deletes the entire current line. 

Interrupts the video display of a 
running program. This sequence 
reactivates the SHBLL and then 
runs the program as a background 
task. 

Upper/lower case shift lock 
function. 

Generates a vertical bar ( | ) char- 
acter. The vertical bar character 
displays as an exclamation point 
(!) in reverse video. 

Generates an up arrow or caret 
( A ) character. 

Generates a left bracket ([) 
character. 

Generates a right bracket (j) 
character. 

Repeats the previous command 
line. 

Redisplays the current command 
line on the video display. 

Temporarily halts output to the 
screen display. Press any key to 
resume output. 

Generates a backslash (/) character. 
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Appendix E Update 



Hard Disk Support 



OS -9 Version 02.00.00 supports the use of 15 or 35 meg 
hard disks through a device driver called CCHDisk. 
CCHDisk lets you use one or more hard disk drives and the 
optional Hard Disk Controller Cartridge in Slot 3 of the 
Multi-Pak Interface. The descriptors for the two types of hard 
disks are contained within the CONFIG utility as: 

h0 15 Drive 15 meg hard disk 

hi _15 Drive 1 15 meg hard disk 

h0 35 Drive 35 meg hard disk 

hi 35 Drive 1 35 meg hard disk 

When the SYSGO module starts the system, it attempts to 
change to the hard disk, if one is attached. If you have a 
hard disk and the appropriate driver and descriptors, your 
execution directory is /H0/CMDS and your data directory is 
/H0. 

The device descriptor for the hard disk is different than for 
floppy diskettes. The following charts provide the data for the 
Color Computer Hard Disk descriptors and disk drive units: 



Descriptor for Color Computer Hard Disk 


IT. DTP 


- 1 (RBF) 


IT. DRV 


= drive number - 3 


IT.STP 


= step rate, see table 


IT.TYP 


- % 100000000 Hard disk Hag for bit 7 


IT. DNS 


— unused 


1T.CYL 


~ number of cylinders (see chart) 


IT.SID 


= number of heads (see chart) 


IT.VFY 


= write verify bit = on : >0 = off 
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Descriptor for Color Computer Hard Disk 


IT. set 


= sectors/traek (see chart) 


IT.TOS 


= sectors/track (see chart) 


IT.ILV 


= sector interleave 


IT.SAS 


= segment allocation size (CoCo — 1 ) 


IT.TFM 


= not used, DMA only 


IT.Exten 


= not used, level II only 


ITSToff 


= not used, level 11 only 



Step 


Rates for WD 1010 Controller 


Code 


Rate 





35 us 


1 


0.5 ms 


2 


1.0 ms 


3 


1.5 ms 


4 


2.0 ms 


5 


2.5 ms 


6 


3.0 ms 


7 


3.5 ms 


8 


4.0 ms 


9 


4.5 ms 


10 


5.0 ms 


11 


5.5 ms 


12 


6.0 ms 


13 


6.5 ms 


14 


7.0 ms 


15 


7.5 ms 



Cylinder/Head chart for TANDY Hard Disks 


Disk 


Heads 


Cylinders 


TPI 


SPT 


Pre-Comp 


15 meg 

35 meg 


6 

8 


306 
512 


345 
512 


32 
34 


128 
256 
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Six bytes are added to the end of the hard disk descriptor that 
are not copied to the path descriptor. They are used at initial- 
ization to set up the parameters for the specific drive type. 
Therefore, if you have more than one hard disk drive, they 
must be of the same type as the first drive. These bytes start 
at offset $25 in the device descriptor and are described in the 
following chart. 



Offset 


Function 


$25 


Write Pre-Comp cylinder number /4 (see 




chart) 


$26 


The number of digits in the cylinder address, 




DIVA value for the driver 


$27 


Normalized divisor for the division routine, 




DIVY value 


$29 


DIVU value, MSB = mask for quotient 




LSB — shift value for 




remainder 


$2B 


Format gap value 



Most values are used for the division routines to convert 
LSN's from RBF into a cylinder number, sector number, and 
head number. 



Color Computer I/O Devices 



Several new input/output devices are available for the Color 
Computer operating under OS-9. The OS-9 system diskette 
contains drivers for the standard devices and the CONFIG/ 
BOOT diskette contains drivers and descriptor modules for 
other devices. This section provides information about the 
devices available using OS-9. 
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SCF-Type Devices 



SCF-typc devices are those that operate on character oriented 
data and deal with only one character at a time. Full infor- 
mation on the SCF is found in the Sequential Character File 
Manager chapter in the OS -9 Technical Information manual. 
The SCF-type devices supported include: 

TERM — for the keyboard video display 
P— for a serial printer 
Tl, T2, and T3— for external terminals 
M 1 and M2— for external modems 
SSC— for a voice synthesizer 

Parity and Baud Rates 

Under OS-9 Version 02.00.00 and higher, external serial 
devices P, Tl, T2, T3, Ml, and M2 have the capability of 
changing their baud rates, parity, stop bits, and word length 
parameters any time they are in use. Such changes are han- 
dled by SCF, through the SS.ComSt SETSTAT. Two bytes in 
the device descriptor hold information about parity and baud 
rates for these devices. These bytes can initialize similar 
bytes in the path descriptor. 

A driver can then use these bytes to change its operating 
parameters through the SETSTAT call. TMODE and XMODE 
give you access to these bytes for examination or change. 
The two bytes are used as follows: 

Baud Byte — supplies information on baud rate, word 
length and stop bits 

IT.BAU— for device descriptor 
PD.BAU — for path descriptor 
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Bits 0-3 Baud rate code: 

= 110 

1 = 300 

2 - 600 

3 = 1200 

4 = 2400 

5 = 4800 

6 = 9600 

7 - 19. 2K 

Note: on some devices, all values might 
not be obtainable or alterable. 

Bit 4 Reserved 

Bits 5-6 Word length code: 

00-8 bit 
01 = 7 bit 

Bit 7 Stop bit code: 

00 = 1 stop bit 
01=2 stop bits 

Parity Byte — supplies information on parity. 
IT.TYP— for the device descriptor 
PD. PAR— for the path descriptor 

Bits 0-3 Reserved 

Bit 4 Modem support feature (Tl, T2, T3, 

Ml, M2 only) 

Bits 5-7 Parity code: 

XX0 - no parity (X - 1 or 0) 

101 = MARK parity transmitted, no 

parity check 

111 = SPACE parity transmitted, no 

parity check 
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The true ASCIA devices (T2, T3, Ml, and M2) also 
support these additional parity codes: 

001 = ODD parity transmitted and 

received 
0] 1 = EVEN parity transmitted and 

received 

Reserved bytes can be used differently by different 
devices. They are noted in their individual sections. 



TERM 



Uses Keyboard/video display 

Modules Required TERM 

CCIO 

Additional I/O subroutine modules 

Features include: 

Lowercase and TERM does not use the baud byte and 
80 column has a different use for the parity byte. It 

does not handle data communications 
through a specific port, but directly 
reads the keyboard and writes to the 
video display: 

Bit Is used as a flag for true 
lowercase on compatible 
machines 

Bit 1 Is used to distinguish 
display size. = 32 
columns, 1 = 80 
columns through an 
external 80 column card. 
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Display Screen SCF devices now have full support for 
varying display screen sizes. The device 
descriptor has two bytes for this pur- 
pose, IT. COL and IT.ROW. These two 
bytes contain information for the number 
of columns and rows available for dis- 
play. You can use an OS-9 GetStat call 
to access this information. The standard 
display screen format is 32 columns. An 
optional text display is available for 80 
column text using a monitor and an 80 
column cartridge in a Multi-Pak Expan- 
sion Interface. The CO80 I/O subroutine 
module handles the text output for this 
card. Many of the OS-9 utilities can now 
adapt to either 32 or 80 column output. 

While the 32 column display module is 
standard, and included in the standard 
OS-9 system boot, the modules for both 
32 and 80 column displays are available 
through the CONFIG utility. If you want 
to use a monitor and an 80 column dis- 
play with the 80 column cartridge, create 
a boot that uses the TERM80 and CO80 
modules with CONFIG. Should you 
wish, you can use CONFIG to restore 
the 32 column standard display. 

Graphics Basic graphics routines that do not 

require drawing on the graphics screen 
are handled directly by CCIO. All draw- 
ing routines pass to GRFO for 
processing. 
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The graphics module, GRFO, resides in 
the CMDS directory of your system 
diskette. You can load GRFO into mem- 
ory using the LOAD command, or you 
can include it in the system boot file 
using CONFIG. GRFO is needed only if 
you wish to use the built-in OS-9 draw 
commands for lines, points, circles and 
fills. For more information on the alpha 
and graphics modes, see Appendix B of 
this addendum. 

Following is a table summarizing the I/O subroutine modules 
supported: 



Name 



Function 



C032 
CO80 
GRFO 



32 column text and semi-graphics output to a 

television display 

80 column text output to a monitor using an 

optional 80 column cartridge 

Graphics output to television display 



Keyboard The Color Computer keyboard can gen- 

Character erate all ASCII characters as well as 

Generation semi graphic characters using [ALT J or 

r@~) . The CCIO also features key repeat 
and type-ahead capabilities. Type-ahead 
is only functional when disk drives are 
not being accessed. Other keyboard fea- 
tures include a terminal bell (Character 
07) which sounds through the television 
speaker, and support for true lowercase 
capability on Color Computers having 
this feature. 



RS-232 External Terminal 



Device descriptor Tl provides serial communication capabil- 
ity through the RS-232 serial port at the rear of the Color 
Computer. You can use this port to support terminal speeds 
as high as 300 baud. Data transfer rates above 300 baud are 
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T2 



unreliable. If data transmission proves unreliable at 300 
baud, use the TUNEPORT utility to adjust the Tl driver for 
the capabilities of your computer. 

Tl supports changeable baud rates, parity (no parity, 
MARK, and SPACE), word length, and stop bits. The default 
settings are: 

• 300 baud 

• no parity 

• 8 data bits 

• 1 stop bit 

Use XMODE or TMODE utilities to configure the port of 
other parameters. 

Tl is set for 80 column displays. Utilities that adapt to dif- 
ferent display sizes, display in 80 columns to an attached 
terminal. 

The Tl and RS232 modules are on the standard OS-9 system 
diskette. 



Use Interrupt driven serial port 

Modules Required T2 

ACIAPAK 
Additional Hardware . . . RS232 Communications Cartridge 

Multi-Pak Expansion Interface 

External Terminal 

The T2 device descriptor uses the optional RS232 Communi- 
cations Card installed in Slot 1 of the Multi-Pak Expansion 
Interface. The associated device driver is named ACIAPAK. 
This port can support a terminal at data transfer rates as high 
as 19.2K baud. T2 expects an 80 column terminal and uses 
an 80 column display mode. T2 provides the following 
features: 

• changeable baud rates, parity, word length, stop bits, 
and X-ON/X-OFF protocol. 
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T3 



• default settings of: 

• 1200 baud 

• no parity 

• 8 data bits 

• 1 stop bit 

Use TMODE or XMODE to change these parameters 
to match your terminal. 

The T2 and ACIAPAK modules are not on the standard OS-9 
system diskette, but you can include them on a system 
diskette using CONFIG. For full information on the hardware 
specifications and pin-out configuration of the communica- 
tions card, see the owner's manual. 



Use Virtual Interrupt driven terminal 

port 
Modules required T3 

MODPAK 
Additional hardware .... RS232 Communications Cartridge 

Multi-Pak Expansion Interface 

Device descriptor T3 provides for a terminal port using the 
optional RS232 Cartridge in Slot 2 of the Multi-Pak Expan- 
sion Interface. The T3 port uses the MODPAK driver, which 
is a virtual interrupt driven driver (see VIRQ in this adden- 
dum). You can use T3 in conjunction with T2. The charac- 
teristics of T3 arc: 

• 300 baud rate only 

• no parity 

• 8 data bits 

• 1 stop bit 

The T3 and MODPAK modules are not included on the stan- 
dard OS-9 system diskette, but you can add them to a system 
diskette using CONFIG. 
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Use Serial printer port 

Modules required P 

PRINTER 
Additional hardware .... Printer 

Device descriptor P uses the PRINTER device driver to pro- 
vide serial printer support through the port at the rear of the 
Color Computer. The port can support a serial printer at data 
transfer rates as high as 9600 baud. If transmission on your 
printer is unreliable, use the TUNEPORT utility to adjust the 
driver for your printer. 

P supports changeable baud rates, parity (no parity, MARK, 
and SPACE), word length, and stop bits. Default settings are: 

• 600 baud 

• no parity 

• 8 data bits 

• 1 stop bit 

• 80 column output 

The PRINTER driver uses the following reserved bits of the 
parity byte: 

Bits 0-3 Timeout value for the printer. The Ready 

status of the printer is checked at Ink/ 
Open time and an error is reported 
immediately. On subsequent writes to 
the printer the timeout value is counted 
down and if the device is not ready when 
it reaches zero, the error is returned. 

P and PRINTER modules are contained on the standard OS-9 
system diskette. 
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Ml 



Use Interrupt driven modem port 

Modules required Ml 

ACIAPAK 

The M 1 deviee descriptor provides future enhancements to 
the Color Computer using Slot 1 of the Multi-Pak Expansion 
Interface. Both Ml and T2 use the ACIAPAK driver and thus 
cannot operate simultaneously. Ml supports a 300 baud 
modem for data communications. It assumes the screen size 
is 80 columns. 

Ml supports changeable parity, word length and stop bits 
through the XMODE utility. The default settings are: 

• 300 baud only 



no parity 



• 



• 8 data bits 



• 



stop bit 



The ACIAPAK driver also supports communications devices 
such as auto answer modems. The Data Carrier Detect line is 
monitored and a transition from MARK to SPACE causes an 
ESHangUp error from a read request, and all Ml opened 
paths are marked for killing by SCF. So, if disconnection 
occurs, all processes started are killed and the next caller 
does not begin where the previous caller ended. 

The kill feature is controlled through bit 4 of the PD.PAR 
byte in the path descriptor or IT. PAR of the device descrip- 
tor. Setting bit 4 enables the kill feature, clearing bit 4 dis- 
ables the feature. Bit 4 also enables the shutdown of RTS and 
DTR at the close of the last path. If bit 4 is cleared, RTS 
and DTR are disabled at terminate rather than at close. (See 
INIZ for information on using IN1Z to keep a device from 
terminating.) 

Ml and ACIAPAK are contained on the CONFIG/BOOT 
diskette, and are not on the standard OS-9 system diskette. 
For information on setup and hardware characteristics of the 
modem cartridge, see the owner's manual for the cartridge. 



74 



M2 



ssc 



Use Virtual Interrupt driven modem 

port 
Modules required M2 

MODPAK 

Device driver M2 provides for future enhancements of the 
Color Computer through Slot 2 of the Multi-Pak Expansion 
Interface. The M2 port uses the virtual interrupt driven 
MODPAK driver (see VIRQ in this addendum). M2 supports 
a 300 baud modem and can be used in conjunction with the 
T2 serial port which requires the RS232 Cartridge in Slot 1 
of the Multi-Pak. 

M2 supports changeable parity, word length, and stop bits 
through the XMODE utility. The default settings are: 

• 300 baud only 

• no parity 

• 8 data bits 

• 1 stop bit 

The M2 and MODPAK modules are not included on the stan- 
dard OS-9 system diskette but you can add them to a system 
disk using CONFIG. 



Use Speech/Sound output port 

Modules required SSC 

SSCPAK 
Additional hardware .... Speech/Sound Cartridge 

Multi-Pak Expansion 

Interface 

The SSC device descriptor supports the optional Speech/ 
Sound Cartridge from Slot 2 or 3 of the Multi-Pak Expansion 
Interface. Speech or sound output is received through the tel- 
evision or monitor speaker. 



75 



NIL 



Use your SSC device in much the same manner as a printer 
(P). Use I/O redirection to send output to the Speech/Sound 
cartridge instead of the video display, or open a path to the 
Speech/Sound Cartridge to write to it. Because the Speech/ 
Sound cartridge uses the same hardware as the joystick ports, 
you cannot use the joysticks and the cartridge simultane- 
ously. If you do, speech or sound is interrupted by a high 
pitched noise from the joysticks. However, you can alternate 
between using speech/sound output and joystick output with- 
out difficulty. 

The SSC and SSCPAK modules are not contained on the 
standard OS-9 system diskette, but you can add to a system 
diskette using CONFIG. 



Use Device for abandoning output 

Modules required NIL 

NILDRV 
Additional hardware .... none 

The NIL device descriptor and the NILDRV driver support a 
null device. Using the device descriptor and driver lets you 
abandon output from a process or enter nothing as input to a 
process. For example, if you run a background process that 
sends messages to the screen, and you do not want them dis- 
played, you can redirect the standard output and standard 
error path to the NIL device. 

NIL and NILDRV are not included on the standard OS-9 sys- 
tem diskette, but you can add them to a system diskette using 
CONFIG. 



RBF-Type Devices 



RBF-type devices are those that handle data in large blocks 
of bytes. See the Random Block File Manager chapter of the 
OS-9 Technical Information manual for information on RBF. 
RBF-type devices supported by OS-9 are floppy disk drives, 
D0-D3 and hard disk drives, H0-H3. 
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D0-D3 



H0-H1 



Uses Floppy disk devices 

Modules required D0 (D1-D3 are optional) 

CCDISK 
Additional hardware .... Floppy disk drives 

Device descriptors D0-D3 are modules that support floppy 
disk drives using the CCDisk device driver. If you are using 
a Multi-Pak Expansion Interface, put the disk controller car- 
tridge in Slot 4 with the Multi-Pak switch set to 4. 

OS -9 requires a minimal system of one floppy disk drive, 
D0. The standard OS-9 system diskette includes the D0 and 
Dl descriptors and the CCDisk driver and supports a two- 
drive system. If you have additional floppy disk units, use 
CONFIG to add the descriptors, D2 or D3, to the boot file. 



Use Hard disk devices 

Modules required H0 (HI for second hard disk) 

CCHDisk 
Additional hardware .... 15 meg or 35 meg hard disk drives 

Color Computer Hard Disk 

Interface Kit 

Multi-Pak Expansion 

Interface 

Device descriptors H0 and HI are modules that support hard 
disk drives using the CCHDisk device driver. Locate the 
Hard Disk Interface cartridge in Slot 3 of the Multi-Pak Inter- 
face Expansion with the floppy disk controller in Slot 4. 

When your OS-9 system initializes, it searches for a device 
/H0. If it is found, the execution directory is set to /H0/ 
CMDS, and the data directory is set to /H0. The H0, HI, 
and CCHDisk modules are not found on the standard OS-9 
system diskette, but you can add them to a system diskette 
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using CONFIG. Hard disk device descriptors are named H0_ 

15. HI — 15, H0__35. and III 35. Information on setting 

up your hard disk drives is contained in the Color Computer 
Hard Disk Interface Kit manual. 



PIPEMAN Devices 



PIPE 



PIPKMAN is the file manager for the OS-9 '"pipe" facility, 
as described in the Advanced Features of the Shell chapter of 
the OS-9 Commands manual. Pipes let data transfer between 
processes by sending the output oi' one process to the input 
of another. There is only one device supported by 
PIPEMAN. 



Use Create a pipeline between two 

processes 
Modules required Pipe 

Piper 
Additional hardware .... None 

The device descriptor PIPE supports OS-9 pipelines in con- 
junction with the PIPER driver. Use an exclamation point (!) 
to tell the SHELL to open a pipeline between two processes. 
The standard output of the first process becomes the standard 
input of the second process. Information on the use of pipes 
is found in Advanced Features of the Shell in the OS-9 Com- 
mands manual. Both PIPE and PIPER are contained on the 
standard OS-9 system diskette. 
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Sample Driver 



Microware OS-9 Assembler 2.1 



00001 
00002 
00003 
00004 
00005 0001 



00006 
00007 
00434 
00435 
00436 

00550 
00551 
00663 
00664 
00863 
00864 
01 001 
01 002 
01171 
01 1 72 
01 1 73 
01 1 74 
01 1 75 
01 1 76 

01 1 78 

01 1 79 

01 1 80 
01 181 

01 182 



000A 

0001 
0000 
0002 

FF40 

0002 
FF68 

FF6C 



if pi 



LEVEL equ 



07/1 0/85 

nam 
tt 1 

use 
1 



CPUType 
CDCDType 
C 1 ocType 
Pwr L nF r q 

DPortset 

AC I AType 
A.T2 

A .M 



use 
opt 



op t 
use 
opt 
u se 
opt 
use 
opt 
use 
opt 



set 

set 
set 
set 

$FF40 

set 
set 

set 



18:04: 00 

Nil Dev ice 

Dr iver Modu 1 e 

def sf i 1 e 



.... /def s/os9def s 
1 

.... /def s/ 
o s9sy sdef s . 1 i 

. . ./defs/o59iodefs 

. . . /def s/os9rbf def s 

. . . /def 5/os95cf def 5 

. . . /defs/sys type 

. ./cc.ass/sysdefs.cc 

Color 

Original 



Hz60 Set frequency 

for U.S. 

Disk controller 

address 

ACI A6551 

$FF68 6551 AC I APak 

Address 

$FF6C Modem Pak 

Addr ess 



01 183 




* endc 




01 184 








01 185 




******************##**#»<i 


*♦******############ 


01 186 




* 




01 187 




* Nil Driver Modu 1 e 




01 188 




* 




011 89 


00E1 


t ype set 


Dr l vr + Ob j c t 


01 190 


0081 


revs set 


ReEnt + 1 


01 191 


0000 


87CD002D mod 


ndrv.end,ndrv.nam, 
type, revs , ndr v . en t 
V.User 
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01 192 
01 193 
01 194 
01 195 
011 96 
01 197 
01 198 
01 199 
01200 
01 201 

01202 
01 203 
01204 
01 205 
01 206 
01 207 
01208 
01 209 
01 21 
01 21 1 
01 21 2 
01 21 3 
01 21 4 
01 21 5 
01 216 

01 21 7 
01218 
01 219 
01 220 
01221 
01 222 



000D 
000E 



001 4 



03 f cb Updat . mode 

4E696C44 ndrv. nam fcs "NilDrv" 

* edition date comments 

* 3 83/02/11 - change read to return EOF 

03 fcb 3 edition number 



001 5 5F ndrv. ent clrb 



00 
20 
00 
00 
00 
00 
00 
00 
00 
00 
00 
00 
00 
00 



16 

1 7 

1 8 

0C 

1 A 

1B 

1C 

1D 

1E 

1 F 

20 

21 

22 

23 

24 

25 



39 

1 2 



1 2 
5F 
39 
1 2 
5F 
39 
1 2 
5F 
39 
1 2 
5F 
39 



rts 
nop 
bra 



nop 

clrb 

rts 

nop 

clrb 

rts 

nop 

clrb 

rts 

nop 

clrb 

rts 



0026 53 ndrv. eof comb 

0027 ldb 
C6D3 

0029 39 rts 

002A FEAA14 emod 
002D ndrv.endequ 

tt 1 



initialize 



ndr v . eof r e t ur n EDF 



write 

ge t s t a t 
pu t s t a t 

terminate 



set carry 

#E$EDF get error codes 



Device Descriptor Module 



Microware OS-9 Assembler 2.1 07/10/85 18:04:16 

Nil Device - Device Descriptor Module 



01 223 
01 224 






01 225 




**♦♦♦**####*■****#*#***#♦*# 


01 226 




* 


01 227 
01 228 




*Nil Device Descriptor Module 
* 


01 229 
01 230 


00F1 

0081 


type set Devic+Objct 
revs set ReEn t + 1 
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01231 

01232 
01233 
01234 

01235 
01236 
01237 
01238 
01239 
01240 
01241 

01242 
01 243 
01 244 
01 245 
01 246 
01 247 
01 248 
01 249 
01 250 
01 251 
01 252 
01253 
01 254 

01 255 
01256 
01 257 
01 258 

01 259 

01 260 

01 261 

01 262 

01 263 
01 264 
01 265 
01 266 
01267 



0000 87CD0039 

000D 03 

000E 000000 

0011 18 



mod 

fcb 
f cb 
fcb 



J12 0C 



001 3 00 

001400 
001 5 00 



0016 
001 7 
0018 
0019 
001 A 
001B 
001 C 
001D 
001E 
001 F 
0020 
0021 
0022 



00 



18 
08 
18 
0D 
1B 
04 
01 
1 7 
03 



fcb 

* DEFAULT PARAMETERS 



ndsc .end,nd5C ,nam,type,rev5 , 

n i lmgr ,nildrv 

UPDAT. mode 

0,0 T null port address 

ndsc.nam-*-1 option byte 

count 
DT.SCF Device type: SCF 



0023 05 

0024 08 

0025 07 
0026 
0000 
0028 
0000 

02A 

4E69EC 

002D 

5343C6 

030 

4E696C44 



fcb 
fcb 
fcb 

fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 
fcb 

fcb 
fcb 
fcb 
fcb 

fcb 

nd 5 c . nam f c s 

nil mg r f c 5 

nildrv f c s 



0036 E07D20 emod 
039 ndsc . end equ 

end 



24 

C$BSP 

C$DEL 

C$CR 

C$E0F 

C$RPRT 

C$RPET 

CSPAUS 

CSINTR 

CSQUIT 
C$B5P 
C$BELL 
,0 



cass-UPPER and lower 
backspace=BS,SP , BS 

de 1 e t e = b k 5 pac e over 

1 i ne 

auto echo on 

auto line feed on 

null count 

end of page pause on 

1 i ne 5 per page 

backspace character 

delete line char 

end of record char 

end of file char 

reprint line char 

dup last line char 

pause char 

keyboard interrupt 

char 

keyboard quit char 

backspace echo char 

line overflow char 

undefined lnit/baud 

rate 

no echo device 



"Nil" device name 
"SCF" file manager 
"NilDrv 11 device driver 

Module CRC 



000000 error(s) 

000000 warning(s) 

$0066 00102 program bytes generated 

$03C3 00963 data bytes allocated 

$2875 10357 bytes used for symbols 
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To OS-9 users. . . 

The new Version 01.01.00 extends the capabilities of your OS-9 Operating System by 
adding new function codes to provide you with more information about the memory, 
the cursor, and the size of your screen. It also enhances your RS/232 cartridge with new 
Comcard support and allows you to patch your clock module to 50 hz. The following 
pages describe the procedures for using the new version. 

These added features reduce the total available memory by only seven pages. In the 
01.01.00 version with the new features added, you still have 62 pages of free space 
available and much greater control of your computer. 

Please note the changes to your OS-9 Technical Information, Commands, and Program 
Development Manuals which are set forth in the following pages. 



OS-9 TECHNICAL INFORMATION MANUAL 

Pages 99-102 should read as follows: 

OS-9 I$Getstt 103F 8D 

Function: 

Returns the status of a file or device. 

This is a "wildcard" call. It is used to handle device parameters that: 

• Are not the same for all devices 

• Are highly hardware-dependent 

• Must be user-changeable 

The exact operation of the GET Status system call depends on the device driver and 
file manager associated with the path. A typical use is to determine a terminars 
parameters for such functions as backspace character, echo on/off. The Get Status call 
is commonly used with Set Status call. 

The Get Status function codes that are currently defined are listed in the "Uses of Get 
Status" section below. 

Entry Conditions: 

A = path number 
B = function code 
(Other registers depend upon function code) 

Exit Conditions: 

Depends upon function code. 

If error: 

CC = C bit set 
B = error code 

Uses of Get Status 

Function codes 7 through 127 are reserved for future use. 

Function codes 128 through 255 and their parameter-passing conventions are user- 
definable. The function code and register stack are passed to the device driver. 



The following function codes are defined: $00, $01, $02, $06, $06, $12, $13, $lc, $26, 
$26. The parameter-passing conventions for these function codes are given below. 

SS.OPT (Function code $00): Reads the option section of the path descriptor 
and copies it into the 32-byte area pointed to by Register X. 

Use this code to determine the current settings for editing functions such as echo 
and auto line feed. For a complete description of the status packet, see the section 

on path descriptors. 

Entry Conditions: 
A = path number 
B = $00 
X = address of place to put a 32-byte status packet 

Exit Conditions: 
Status packet 

If error: 
CC = C bit set 
B = error code 

SS. READY (Function code $01): Tests for data available on SCFMAN- 

supported devices. 

Entry Conditions: 
A = path number 

B = $01 

Exit Conditions: 
If ready: 
CC = C bit clear 
B = $F6 (E$NOTRDY) 

If error: 
CC = C bit set 
B = error code 

SS.SIZE (Function code $02): Gets the current file size (RBFMAN-supported 

devices only). 

Entry Conditions: 
A = path number 
B = $02 



Exit Conditions: 

X = ms 16 bits of the current file size 
U = Is 16 bits of the current file size 

If error: 
CC = C bit set 
B = error code 

SS.POS (Function code $06): Gets the current file position (RBFMAN- 
supported devices only). 

Entry Conditions: 
A = path number 
B = $05 

Exit Conditions: 

X = MS 16 bits of the current file position 
U = LS 16 bits of the current file position 

If error: 
CC = C bit set 
B = error code 

SS.DSTAT (Function code $12): Returns the display status. 

Entry Conditions: 
A — path number 
B = $12 

Exit Conditions: 

X = address of the graphics display memory 

Y = graphics cursor address; x = MSB, y = LSB 

A = color code of the pixel at the cursor address 

SS.Joy (Function code $13): Returns the joystick values. 

Entry Conditions: 
A = path number 
B = $12 

X = (right joystick), or 
X = 1 (left joystick) 



Exit Conditions: 

X = selected joystick x value (0-63) 
Y = selected joystick Y value (0-63) 
A = $FF (if the fire button is on), or 
A = $00 (if the fire button is off) 

SS.Alfas (Function code $lc): Returns information about alpha screen memory. 



Entry Conditions: 




A 


= path number 




B 


= $1C 




Exit Conditions: 




A 


= caps lock status 
00 = lower case 
$FF = upper case 




X 


= address of buffer in 


memory 


Y 


— address of cursor in 


memory 


SS. Cursr (Function code $25): Reti 


Entry Conditions: 




A 


= path number 




B 


= $25 





Exit Conditions: 

A = character under cursor 

X = x position of cursor (column) 

Y = y position of cursor (row) 

SS.ScSiz (Function code $26): Returns size of screen (default from descriptor) 

Entry Conditions: 
A = path number 
B = $26 

Exit Conditions: 

X = number of columns on screen 

Y = number of rows on screen 

Note: Currently these are simply the values in the device descriptors following 
the XOFF byte. Descriptors may be patched to return different values. 



OS-9 COMMANDS MANUAL 

Add the following information to page 15. 

New Comcard Support 

The ACIAPAC driver for the expansion MultiPac interface #26-3024 is included on the 
master disk, along with a device descriptor named *7T2." The Com Board RS/232 car- 
tridge #26-2226 must be plugged into slot #1 of the MultiPac. The disk controller is 
plugged into slot #4 of the MultiPac. X mode and T mode will allow /T2 to use XON/X- 
OFF. To use them make sure your MultiPac cartridge selector switch is in position #4. 

Note: When connecting an RS-232C device, check the device's owner's manual for 
pin out descriptions. 

The Com Board's (#26-2226) Data Set Ready (DSR), Data Carrier Detect (DCD), 
and Clear to Send (CTS) RS-232C handshake lines require active signals. 

Add the following codes to the Display Control codes on page 132. 

Cursor ON-OFF (All numbers are in decimal.) Displaying a code of 05 followed by a 
qualifier code changes the cursor. 



Lead 








in 


C# 


Char 


Function 


04 






Clear to end of line 


05 


32 


(space) 


Cursor OFF 


05 


33 


(!) 


Cursor ON .. Default color (Blue) 


05 


34 


n 


Cursor ON .. Black 


05 


35 


(#) 


Cursor ON .. Green 


05 


36 


($) 


Cursor ON .. Yellow 


05 


37 


(%) 


Cursor ON .. Blue 


05 


38 


<&) 


Cursor ON .. Red 


05 


39 


c) 


Cursor ON .. Buff 


05 


40 


(0 


Cursor ON .. Cyan 


05 


41 


0) 


Cursor ON .. Magenta 


05 


42 


(*) 


Cursor ON .. Orange 


11 






Clear to end of screen 



OS-9 PROGRAM DEVELOPMENT MANUAL 

Add the following information to page 161. 

A command procedure to patch the resident version of the clock module to 50 hz has 
been included on the master disk. To use this command, first make a backup of the 
system master. On the new backup copy type "CLOCKPATCH.COM". After you have 
completed the procedure, reboot the system. 



Thank You! 

Radio Shack 

A Division of Tandy Corporation 



875-9555 



